Payment Links API

Create shareable payment links with customizable styling, usage limits, QR codes, and embed codes. Supports one-time payments and subscription sign-ups.

Base:/v1/PaymentLink

CRUD Operations

Create, read, update, and delete payment links.

GET

/v1/PaymentLink

List Payment Links

Retrieve all payment links with OData filtering, sorting, and pagination.

Query Parameters

Name	Type	Required	Description
$filter	string	Optional	e.g. status eq 'Active'
$orderby	string	Optional	'createdDateTime desc'
$top	number	Optional	Page size
$skip	number	Optional	Offset
$count	boolean	Optional	Include total count

Response

{
  "@odata.count": 42,
  "value": [
    {
      "id": 1,
      "code": "SUMMER-SALE",
      "identifier": "abc-123-def",
      "name": "Summer Sale",
      "productName": "Pro Plan",
      "unitPrice": "49.99",
      "currencyCode": "USD",
      "status": "Active",
      "usageMode": "MultiUse",
      "clickCount": 150,
      "completedPaymentCount": 45,
      "totalAmountCollected": "2249.55",
      "paymentUrl": "https://pay.yardpaypro.com/l/abc-123-def",
      "qrCodeUrl": "/v1/PaymentLink/qr/abc-123-def"
    }
  ]
}

POST

/v1/PaymentLink

Create Payment Link

Create a new payment link with pricing, usage limits, and styling options.

Request Body

{
  "name": "Pro Plan Monthly",
  "description": "Subscribe to the Pro Plan",
  "productName": "Pro Plan",
  "productDescription": "Advanced features for growing businesses",
  "unitPrice": "49.99",
  "quantity": "1",
  "currencyCode": "USD",
  "callToActionText": "Subscribe Now",
  "usageMode": "MultiUse",
  "linkType": "Standard",
  "linkStyle": "Button",
  "buttonColor": "#0066FF",
  "buttonTextColor": "#FFFFFF",
  "validFrom": "2024-03-01T00:00:00Z",
  "validTo": "2024-12-31T23:59:59Z",
  "successUrl": "https://example.com/thank-you",
  "cancelUrl": "https://example.com/cancelled"
}

Response

{
  "id": 1,
  "code": "PRO-PLAN-MONTHLY",
  "identifier": "abc-123-def",
  "paymentUrl": "https://pay.yardpaypro.com/l/abc-123-def",
  "qrCodeUrl": "/v1/PaymentLink/qr/abc-123-def",
  "embedCode": "<a href=\"...\" ...>Subscribe Now</a>",
  "status": "Active",
  ...
}

PATCH

/v1/PaymentLink/{id}

Update Payment Link

Update an existing payment link. Only provided fields are modified.

Path Parameters

Name	Type	Required	Description
id	number	Required	Payment link ID

Request Body

{
  "name": "Pro Plan Monthly (Updated)",
  "unitPrice": "59.99",
  "callToActionText": "Get Started"
}

DELETE

/v1/PaymentLink/{id}

Delete Payment Link

Delete a payment link permanently.

Path Parameters

Name	Type	Required	Description
id	number	Required	Payment link ID

Actions

Activate, deactivate, and retrieve embed codes.

POST

/v1/PaymentLink/{id}/Activate

Activate Payment Link

Activate a draft or inactive payment link to start accepting payments.

Path Parameters

Name	Type	Required	Description
id	number	Required	Payment link ID

POST

/v1/PaymentLink/{id}/Deactivate

Deactivate Payment Link

Deactivate an active payment link. Customers will see it as unavailable.

Path Parameters

Name	Type	Required	Description
id	number	Required	Payment link ID

GET

/v1/PaymentLink/{id}/EmbedCode

Get Embed Code

Retrieve the HTML embed code and payment URL for a payment link.

Path Parameters

Name	Type	Required	Description
id	number	Required	Payment link ID

Response

{
  "embedCode": "<a href=\"https://pay.yardpaypro.com/l/abc-123\" style=\"...\">Subscribe Now</a>",
  "paymentUrl": "https://pay.yardpaypro.com/l/abc-123"
}

Public Endpoints

Endpoints used by the hosted payment page. No authentication required.

GET

/v1/PaymentLink/GetByIdentifier(identifier='{identifier}')

Public

Get by Identifier

Retrieve a payment link by its public identifier. Used by the payment page to load link details.

Path Parameters

Name	Type	Required	Description
identifier	string	Required	Payment link identifier (UUID)

GET

/v1/PaymentLink/GetByMerchantSlug(merchantSlug='{slug}',code='{code}')

Public

Get by Merchant Slug

Retrieve a payment link using the merchant slug and link code. Used for vanity URLs.

Path Parameters

Name	Type	Required	Description
slug	string	Required	Merchant slug
code	string	Required	Payment link code

POST

/v1/PaymentLink/CreateInvoice(identifier='{identifier}')

Public

Create Invoice from Link

Create an invoice from a payment link for one-time payments. Returns an invoice that can be paid via the Payments API.

Path Parameters

Name	Type	Required	Description
identifier	string	Required	Payment link identifier

Request Body

{
  "email": "[email protected]",
  "firstName": "John",
  "lastName": "Doe"
}

POST

/v1/PaymentLink/CreateSubscription(identifier='{identifier}')

Public

Create Subscription from Link

Create a subscription from a subscription-type payment link. Returns a subscription with billing details.

Path Parameters

Name	Type	Required	Description
identifier	string	Required	Payment link identifier

Request Body

{
  "email": "[email protected]",
  "firstName": "John",
  "lastName": "Doe",
  "planId": 1
}

POST

/v1/PaymentLink/SendVerificationCode(identifier='{identifier}')

Public

Send Verification Code

Send an email verification code before allowing payment. Used when the link requires email verification.

Path Parameters

Name	Type	Required	Description
identifier	string	Required	Payment link identifier

Request Body

{
  "email": "[email protected]"
}

Response

{
  "tokenId": "tok_abc123",
  "message": "Verification code sent",
  "expiresAt": "2024-03-15T10:15:00Z",
  "email": "[email protected]"
}

Enums

PaymentLinkStatus

Draft

Active

Inactive

Expired

Exhausted

Archived

PaymentLinkUsageMode

MultiUse

SingleUse

LimitedUse

PaymentLinkType

Standard

Subscription

PaymentLinkStyle

Link

Button

Types

PaymentLinkDto

interface PaymentLinkDto {
  id: number;
  code: string;                     // Short code (e.g. "SUMMER-SALE")
  identifier: string;               // UUID for public URLs
  name: string;
  description?: string;
  callToActionText?: string;        // Button/link label

  // Product info
  productCode?: string;
  productName?: string;
  productDescription?: string;

  // Pricing
  unitPrice: string;                // Decimal as string
  quantity: string;
  currencyCode: string;
  isVariableAmount: boolean;        // Customer chooses amount
  minAmount?: string;
  maxAmount?: string;
  suggestedAmount?: string;
  taxRate: string;
  taxAmount: string;

  // Status & validity
  status: PaymentLinkStatus;
  validFrom: string;
  validTo?: string;

  // Usage control
  usageMode: PaymentLinkUsageMode;
  maxUses?: number;                 // null = unlimited
  maxUsesPerCustomer?: number;

  // Styling
  linkType: PaymentLinkType;
  linkStyle: PaymentLinkStyle;
  buttonColor?: string;
  buttonTextColor?: string;
  mediaUrl?: string;

  // URLs
  paymentUrl?: string;              // Hosted payment page URL
  qrCodeUrl?: string;               // QR code image URL
  embedCode?: string;               // HTML embed snippet
  successUrl?: string;              // Redirect after payment
  cancelUrl?: string;               // Redirect on cancel
  notificationUrl?: string;         // Webhook URL

  // Security
  isPasswordProtected: boolean;
  isEmailVerificationRequired: boolean;

  // Analytics
  clickCount: number;
  invoiceCount: number;
  completedPaymentCount: number;
  totalAmountCollected: string;

  // Subscription
  isSubscriptionBased: boolean;
  subscriptionProductId?: number;
}

Usage Examples

Create a payment link and get embed code

TypeScript

const { data: link } = await client.post('/v1/PaymentLink', {
  name: 'Pro Plan',
  productName: 'Pro Plan Monthly',
  unitPrice: '49.99',
  quantity: '1',
  currencyCode: 'USD',
  callToActionText: 'Subscribe Now',
  usageMode: 'MultiUse',
  linkType: 'Standard',
  linkStyle: 'Button',
  buttonColor: '#0066FF',
  successUrl: 'https://example.com/thank-you',
});

// Get shareable URL
console.log(link.paymentUrl);
// "https://pay.yardpaypro.com/l/abc-123-def"

// Get HTML embed code
const { data: embed } = await client.get(
  `/v1/PaymentLink/${link.id}/EmbedCode`
);
console.log(embed.embedCode);
// <a href="..." style="...">Subscribe Now</a>

Customer-facing: create invoice from payment link

TypeScript

// No auth required — public endpoint
const { data: invoice } = await axios.post(
  "/v1/PaymentLink/CreateInvoice(identifier='abc-123-def')",
  {
    email: '[email protected]',
    firstName: 'John',
    lastName: 'Doe',
  }
);

// Pay the invoice using the Payments API
const payment = await axios.post(
  '/api/payment/payinvoice',
  {
    invoiceId: invoice.id,
    paymentOptionId: 1,
    card: { ... },
  },
  { headers: { 'x-api-key': API_KEY } }
);