---
updatedAt: 2026-02-04T06:35:25.000Z
agentTools:
  projectIndex: https://checkout-docs.transfi.com/llms.txt
---

# Create Payment Invoice

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

## Authentication - HMAC-SHA256

All requests MUST include custom headers for security and verification:

**Required Headers:**
- `Content-Type`: Must be `application/json`
- `x-api-key`: Merchant's Public Key (pk_...)
- `x-timestamp`: Current time in milliseconds (e.g., 1758957600000)
- `x-signature`: HMAC-SHA256 hash
- `X-Api-Version`: API version (`v1`)

**Optional Headers:**
- `x-trace-id`: Request trace ID for logging

## HMAC Signature Calculation

```javascript
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');
```

## Environment & Security

- Organizations with status !== 'live' can only use sandbox API keys
- Live organizations can use both sandbox and live API keys
- Production requests must come from whitelisted IPs


# OpenAPI definition

````json
{
  "openapi": "3.0.3",
  "info": {
    "title": "TransFi Payment Invoice API",
    "description": "# TransFi Payment Invoice API\n\nCreate dynamic payment invoices tied to payment link templates. This API enables merchants to generate unique payment URLs for each customer transaction with custom amounts, product details, and customer information.\n\n## Authentication\n\nThis API uses **HMAC-SHA256** signature-based authentication. All requests must include the following headers:\n\n- `x-api-key`: Your Public Key (pk_...)\n- `x-timestamp`: Current time in milliseconds since Unix epoch\n- `x-signature`: HMAC-SHA256 hash calculated from request details\n- `X-Api-Version`: API version (currently `v1`)\n\n### Signature Calculation\n\n```javascript\nconst crypto = require('crypto');\nconst message = method + path + timestamp + body;\nconst signature = crypto.createHmac('sha256', secretKey).update(message).digest('hex');\n```\n\n## Environments\n\n- **Production**: `https://checkout-server.transfi.com`\n- **Sandbox**: `https://checkout-server-sandbox.transfi.com`\n\n## Support\n\n- Email: support@transfi.com\n- Documentation: https://docs.transfi.com\n- Dashboard: https://dashboard.transfi.com\n",
    "version": "1.0.0",
    "contact": {
      "name": "TransFi Support",
      "email": "support@transfi.com",
      "url": "https://transfi.com"
    },
    "license": {
      "name": "UNLICENSED"
    },
    "termsOfService": "https://transfi.com/terms"
  },
  "servers": [
    {
      "url": "https://checkout-server.transfi.com",
      "description": "Production Server"
    },
    {
      "url": "https://checkout-server-sandbox.transfi.com",
      "description": "Sandbox Server (for testing)"
    }
  ],
  "tags": [
    {
      "name": "Payment Invoice",
      "description": "Create and manage dynamic payment invoices"
    }
  ],
  "security": [
    {
      "HmacAuth": []
    }
  ],
  "paths": {
    "/checkout/payment-link/invoice": {
      "post": {
        "tags": [
          "Payment Invoice"
        ],
        "summary": "Create Payment Invoice",
        "description": "Creates a dynamic invoice tied to a specific payment link template, allowing merchants to pass customer and product details.\n\n## Authentication - HMAC-SHA256\n\nAll requests MUST include custom headers for security and verification:\n\n**Required Headers:**\n- `Content-Type`: Must be `application/json`\n- `x-api-key`: Merchant's Public Key (pk_...)\n- `x-timestamp`: Current time in milliseconds (e.g., 1758957600000)\n- `x-signature`: HMAC-SHA256 hash\n- `X-Api-Version`: API version (`v1`)\n\n**Optional Headers:**\n- `x-trace-id`: Request trace ID for logging\n\n## HMAC Signature Calculation\n\n```javascript\nconst method = 'POST';\nconst path = '/checkout/payment-link/invoice';\nconst timestamp = Date.now().toString();\nconst body = JSON.stringify(requestBody);\nconst message = method + path + timestamp + body;\nconst signature = crypto.createHmac('sha256', SECRET_KEY).update(message).digest('hex');\n```\n\n## Environment & Security\n\n- Organizations with status !== 'live' can only use sandbox API keys\n- Live organizations can use both sandbox and live API keys\n- Production requests must come from whitelisted IPs\n",
        "operationId": "createPaymentInvoice",
        "parameters": [
          {
            "name": "x-api-key",
            "in": "header",
            "required": true,
            "description": "The Merchant's Public Key (pk_...) for identification",
            "schema": {
              "type": "string",
              "example": "pk_1234567890abcdef",
              "pattern": "^pk_[a-zA-Z0-9]+$"
            }
          },
          {
            "name": "x-timestamp",
            "in": "header",
            "required": true,
            "description": "Current time in milliseconds since Unix epoch - Used to prevent replay attacks",
            "schema": {
              "type": "string",
              "example": "1758957600000",
              "pattern": "^\\d{13}$"
            }
          },
          {
            "name": "x-signature",
            "in": "header",
            "required": true,
            "description": "HMAC-SHA256 hash calculated as: \ncrypto.createHmac('sha256', secretKey).update(method + path + timestamp + body).digest('hex')\n",
            "schema": {
              "type": "string",
              "example": "a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456",
              "pattern": "^[a-f0-9]{64}$"
            }
          },
          {
            "name": "X-Api-Version",
            "in": "header",
            "required": true,
            "description": "API version, currently fixed at v1",
            "schema": {
              "type": "string",
              "enum": [
                "v1"
              ],
              "example": "v1"
            }
          },
          {
            "name": "x-trace-id",
            "in": "header",
            "required": false,
            "description": "Optional trace ID for request tracking and debugging",
            "schema": {
              "type": "string",
              "example": "trace-abc123-def456"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "description": "Invoice details with customer and product information",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateInvoiceRequest"
              },
              "examples": {
                "complete": {
                  "summary": "Complete Example with All Fields",
                  "value": {
                    "paymentLinkId": "68f86e65a530b2baa9866831",
                    "amount": "100",
                    "currency": "USD",
                    "productDetails": {
                      "name": "Premium Product",
                      "description": "High quality product with 1-year warranty",
                      "imageUrl": "https://example.com/product-image.jpg"
                    },
                    "individual": {
                      "firstName": "John",
                      "lastName": "Doe",
                      "phone": "1234567890",
                      "phoneCode": "+1",
                      "email": "john.doe@example.com",
                      "country": "US",
                      "address": {
                        "street": "1600 Amphitheatre Parkway",
                        "city": "Mountain View",
                        "state": "California",
                        "postalCode": "94043"
                      }
                    },
                    "successRedirectUrl": "https://yoursite.com/payment/success",
                    "failureRedirectUrl": "https://yoursite.com/payment/failure",
                    "customerOrderId": "order-1758957600000"
                  }
                },
                "minimal": {
                  "summary": "Minimal Example with Required Fields Only",
                  "value": {
                    "paymentLinkId": "68f86e65a530b2baa9866831",
                    "amount": "100",
                    "currency": "USD",
                    "productDetails": {
                      "name": "Premium Product"
                    },
                    "individual": {
                      "firstName": "John",
                      "lastName": "Doe"
                    },
                    "successRedirectUrl": "https://yoursite.com/success",
                    "failureRedirectUrl": "https://yoursite.com/failure",
                    "customerOrderId": "order-1758957600000"
                  }
                },
                "subscription": {
                  "summary": "Subscription Payment Example",
                  "value": {
                    "paymentLinkId": "68f86e65a530b2baa9866831",
                    "amount": "29.99",
                    "currency": "USD",
                    "productDetails": {
                      "name": "Premium Monthly Subscription",
                      "description": "Access to all premium features for 30 days",
                      "imageUrl": "https://example.com/subscription-badge.jpg"
                    },
                    "individual": {
                      "firstName": "Jane",
                      "lastName": "Smith",
                      "email": "jane.smith@example.com"
                    },
                    "successRedirectUrl": "https://yoursite.com/subscription/activated",
                    "failureRedirectUrl": "https://yoursite.com/subscription/failed",
                    "customerOrderId": "sub-1758957600000"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Invoice created successfully - Returns payment URL for customer checkout",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreateInvoiceSuccessResponse"
                },
                "examples": {
                  "success": {
                    "summary": "Successful Invoice Creation",
                    "value": {
                      "success": true,
                      "data": {
                        "success": true,
                        "paymentUrl": "https://checkout-widget.transfi.com/checkout/payment-link/697b386a48ec1f740b8c2231"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad Request - Invalid request data, missing required fields, or validation errors",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "missingAmount": {
                    "summary": "Missing Required Field",
                    "value": {
                      "statusCode": 400,
                      "message": "Validation failed: amount is required",
                      "error": "Bad Request"
                    }
                  },
                  "invalidCurrency": {
                    "summary": "Invalid Currency Code",
                    "value": {
                      "statusCode": 400,
                      "message": "Validation failed: currency must be a valid ISO 4217 code",
                      "error": "Bad Request"
                    }
                  },
                  "invalidEmail": {
                    "summary": "Invalid Email Format",
                    "value": {
                      "statusCode": 400,
                      "message": "Validation failed: email must be a valid email address",
                      "error": "Bad Request"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Invalid API key, missing/invalid timestamp, or invalid HMAC signature",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "invalidSignature": {
                    "summary": "Invalid HMAC Signature",
                    "value": {
                      "statusCode": 401,
                      "message": "Invalid signature",
                      "error": "Unauthorized"
                    }
                  },
                  "invalidApiKey": {
                    "summary": "Invalid API Key",
                    "value": {
                      "statusCode": 401,
                      "message": "Invalid API key",
                      "error": "Unauthorized"
                    }
                  },
                  "missingTimestamp": {
                    "summary": "Missing Timestamp",
                    "value": {
                      "statusCode": 401,
                      "message": "Missing timestamp",
                      "error": "Unauthorized"
                    }
                  },
                  "expiredTimestamp": {
                    "summary": "Timestamp Too Old",
                    "value": {
                      "statusCode": 401,
                      "message": "Invalid timestamp",
                      "error": "Unauthorized"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - API key inactive/expired, IP not whitelisted, or environment not authorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "ipNotWhitelisted": {
                    "summary": "IP Not Whitelisted",
                    "value": {
                      "statusCode": 403,
                      "message": "IP address not whitelisted",
                      "error": "Forbidden"
                    }
                  },
                  "apiKeyInactive": {
                    "summary": "API Key Inactive",
                    "value": {
                      "statusCode": 403,
                      "message": "API key is inactive",
                      "error": "Forbidden"
                    }
                  },
                  "apiKeyExpired": {
                    "summary": "API Key Expired",
                    "value": {
                      "statusCode": 403,
                      "message": "API key has expired",
                      "error": "Forbidden"
                    }
                  },
                  "sandboxInProduction": {
                    "summary": "Sandbox Key in Production",
                    "value": {
                      "statusCode": 403,
                      "message": "Sandbox API key cannot be used in production",
                      "error": "Forbidden"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not Found - Payment link ID does not exist or has been deleted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "notFound": {
                    "summary": "Payment Link Not Found",
                    "value": {
                      "statusCode": 404,
                      "message": "Payment link not found",
                      "error": "Not Found"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error - Unexpected server error during invoice creation",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "serverError": {
                    "summary": "Internal Server Error",
                    "value": {
                      "statusCode": 500,
                      "message": "Internal server error",
                      "error": "Internal Server Error"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "HmacAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "x-signature",
        "description": "HMAC-SHA256 signature authentication. \n\nCalculate signature as:\n```\nmessage = method + path + timestamp + body\nsignature = HMAC-SHA256(message, secretKey).toHex()\n```\n\nAlso required:\n- x-api-key: Public Key\n- x-timestamp: Current timestamp in milliseconds\n- X-Api-Version: v1\n"
      }
    },
    "schemas": {
      "CreateInvoiceRequest": {
        "type": "object",
        "required": [
          "paymentLinkId",
          "amount",
          "currency",
          "productDetails",
          "individual",
          "successRedirectUrl",
          "failureRedirectUrl",
          "customerOrderId"
        ],
        "properties": {
          "paymentLinkId": {
            "type": "string",
            "description": "Unique ID of the payment link template created in the Merchant Dashboard",
            "example": "68f86e65a530b2baa9866831",
            "pattern": "^[a-f0-9]{24}$"
          },
          "amount": {
            "type": "string",
            "description": "Payment amount (passed as string to avoid floating-point precision errors)",
            "example": "100",
            "pattern": "^\\d+(\\.\\d{1,2})?$"
          },
          "currency": {
            "type": "string",
            "description": "Three-letter currency code (ISO 4217)",
            "example": "USD",
            "pattern": "^[A-Z]{3}$",
            "enum": [
              "USD",
              "EUR",
              "GBP",
              "JPY",
              "AUD",
              "CAD",
              "CHF",
              "CNY",
              "INR",
              "SGD",
              "HKD",
              "NZD",
              "SEK",
              "KRW",
              "NOK",
              "MXN",
              "BRL",
              "ZAR",
              "RUB",
              "TRY"
            ]
          },
          "productDetails": {
            "$ref": "#/components/schemas/ProductDetails"
          },
          "individual": {
            "$ref": "#/components/schemas/Individual"
          },
          "successRedirectUrl": {
            "type": "string",
            "format": "uri",
            "description": "URL to redirect the user to after a successful payment",
            "example": "https://yoursite.com/payment/success"
          },
          "failureRedirectUrl": {
            "type": "string",
            "format": "uri",
            "description": "URL to redirect the user to after a failed payment",
            "example": "https://yoursite.com/payment/failure"
          },
          "customerOrderId": {
            "type": "string",
            "description": "Unique order identifier from the merchant's system. \nHighly recommended to use a unique identifier like order-{{timestamp}}\n",
            "example": "order-1758957600000",
            "minLength": 1,
            "maxLength": 100
          }
        }
      },
      "ProductDetails": {
        "type": "object",
        "required": [
          "name"
        ],
        "properties": {
          "name": {
            "type": "string",
            "description": "Name of the product or service",
            "example": "Premium Product",
            "minLength": 1,
            "maxLength": 200
          },
          "description": {
            "type": "string",
            "description": "Detailed description of the product or service",
            "example": "High quality product with 1-year warranty",
            "maxLength": 1000
          },
          "imageUrl": {
            "type": "string",
            "format": "uri",
            "description": "URL to an image of the product (displayed in checkout)",
            "example": "https://example.com/product-image.jpg"
          }
        }
      },
      "Individual": {
        "type": "object",
        "required": [
          "firstName",
          "lastName"
        ],
        "properties": {
          "firstName": {
            "type": "string",
            "description": "Customer's legal first name",
            "example": "John",
            "minLength": 1,
            "maxLength": 100
          },
          "lastName": {
            "type": "string",
            "description": "Customer's legal last name",
            "example": "Doe",
            "minLength": 1,
            "maxLength": 100
          },
          "phone": {
            "type": "string",
            "description": "Phone number without country code",
            "example": "1234567890",
            "pattern": "^\\d{7,15}$"
          },
          "phoneCode": {
            "type": "string",
            "description": "Country phone code with + prefix",
            "example": "+1",
            "pattern": "^\\+\\d{1,4}$"
          },
          "email": {
            "type": "string",
            "format": "email",
            "description": "Customer's email address",
            "example": "john.doe@example.com"
          },
          "country": {
            "type": "string",
            "description": "Two-letter country code (ISO 3166-1 alpha-2)",
            "example": "US",
            "pattern": "^[A-Z]{2}$"
          },
          "address": {
            "$ref": "#/components/schemas/Address"
          }
        }
      },
      "Address": {
        "type": "object",
        "properties": {
          "street": {
            "type": "string",
            "description": "Building number and street name",
            "example": "1600 Amphitheatre Parkway",
            "maxLength": 200
          },
          "city": {
            "type": "string",
            "description": "City name",
            "example": "Mountain View",
            "maxLength": 100
          },
          "state": {
            "type": "string",
            "description": "State or province",
            "example": "California",
            "maxLength": 100
          },
          "postalCode": {
            "type": "string",
            "description": "ZIP code or postal code",
            "example": "94043",
            "maxLength": 20
          }
        }
      },
      "CreateInvoiceSuccessResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "description": "Indicates successful invoice creation",
            "example": true
          },
          "data": {
            "type": "object",
            "properties": {
              "success": {
                "type": "boolean",
                "description": "Inner success flag",
                "example": true
              },
              "paymentUrl": {
                "type": "string",
                "format": "uri",
                "description": "Unique payment URL for the customer to complete the payment",
                "example": "https://checkout-widget.transfi.com/checkout/payment-link/697b386a48ec1f740b8c2231"
              }
            }
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "statusCode": {
            "type": "integer",
            "description": "HTTP status code",
            "example": 400
          },
          "message": {
            "type": "string",
            "description": "Error message describing what went wrong",
            "example": "Validation failed"
          },
          "error": {
            "type": "string",
            "description": "Error type",
            "example": "Bad Request",
            "enum": [
              "Bad Request",
              "Unauthorized",
              "Forbidden",
              "Not Found",
              "Internal Server Error"
            ]
          }
        }
      }
    }
  },
  "x-tagGroups": [
    {
      "name": "Payment APIs",
      "tags": [
        "Payment Invoice"
      ]
    }
  ]
}
````