Create a Checkout Form

Create a Checkout Form to accept payment details from buyers. Checkout Forms are a low-code solution that enables you to create a customizable payment page where buyers can easily enter their payment details and submit a payment on both desktop and mobile devices.

Overview

Checkout Forms provide:

• Hosted payment pages with customizable branding
• PCI-compliant payment collection (no sensitive data touches your servers)
• Mobile-optimized checkout experience
• Flexible payment options (cards, bank accounts)
• One-time or recurring payment support
• Split payments for marketplaces

Use Cases

1. Basic One-Time Payment

Create a simple checkout form for a single payment:

async function createBasicCheckoutForm(merchantId, amount) {
  const response = await fetch(
    'https://api.ahrvo.network/payments/na/checkout_forms',
    {
      method: 'POST',
      headers: {
        'Authorization': 'Basic ' + btoa('username:password'),
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        merchant_id: merchantId,
        payment_frequency: 'ONE_TIME',
        allowed_payment_methods: ['PAYMENT_CARD'],
        amount_details: {
          amount_type: 'FIXED',
          total_amount: amount,
          currency: 'USD'
        },
        additional_details: {
          collect_name: true,
          collect_email: true,
          expiration_in_minutes: 10080 // 7 days
        }
      })
    }
  );
  
  const form = await response.json();
  
  console.log('Checkout Form Created:');
  console.log('URL:', form.link_url);
  console.log('Expires:', form.link_expires_at);
  
  return form;
}

2. E-Commerce Checkout with Items

Create checkout for product purchases:

async function createProductCheckout(merchantId, products) {
  const subtotal = products.reduce((sum, p) => sum + (p.price * p.quantity), 0);
  const shipping = 995; // $9.95
  const tax = Math.round(subtotal * 0.08); // 8% tax
  const total = subtotal + shipping + tax;
  
  const response = await fetch(
    'https://api.ahrvo.network/payments/na/checkout_forms',
    {
      method: 'POST',
      headers: {
        'Authorization': 'Basic ' + btoa('username:password'),
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        merchant_id: merchantId,
        payment_frequency: 'ONE_TIME',
        allowed_payment_methods: ['PAYMENT_CARD', 'BANK_ACCOUNT'],
        nickname: 'Product Purchase',
        items: products.map(product => ({
          name: product.name,
          description: product.description,
          quantity: product.quantity.toString(),
          price_details: {
            sale_amount: product.price,
            currency: 'USD',
            price_type: product.on_sale ? 'PROMOTIONAL' : 'REGULAR',
            regular_amount: product.regular_price || product.price
          },
          image_details: {
            primary_image_url: product.image_url
          }
        })),
        amount_details: {
          amount_type: 'FIXED',
          total_amount: total,
          currency: 'USD',
          amount_breakdown: {
            subtotal_amount: subtotal,
            shipping_amount: shipping,
            estimated_tax_amount: tax
          }
        },
        additional_details: {
          collect_name: true,
          collect_email: true,
          collect_shipping_address: true,
          success_return_url: 'https://yoursite.com/order/success',
          cart_return_url: 'https://yoursite.com/cart'
        }
      })
    }
  );
  
  return await response.json();
}

3. Custom Branded Checkout

Create checkout with your brand colors and logo:

async function createBrandedCheckout(merchantId, brandConfig) {
  const response = await fetch(
    'https://api.ahrvo.network/payments/na/checkout_forms',
    {
      method: 'POST',
      headers: {
        'Authorization': 'Basic ' + btoa('username:password'),
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        merchant_id: merchantId,
        payment_frequency: 'ONE_TIME',
        allowed_payment_methods: ['PAYMENT_CARD'],
        amount_details: {
          amount_type: 'FIXED',
          total_amount: 5000,
          currency: 'USD'
        },
        branding: {
          brand_color: brandConfig.primaryColor, // e.g., '#FF06B5'
          accent_color: brandConfig.accentColor, // e.g., '#000000'
          button_font_color: brandConfig.buttonTextColor, // e.g., '#FFFFFF'
          logo: brandConfig.logoUrl,
          icon: brandConfig.faviconUrl,
          logo_alternative_text: brandConfig.companyName
        },
        additional_details: {
          collect_name: true,
          collect_email: true,
          success_return_url: brandConfig.successUrl,
          terms_of_service_url: brandConfig.termsUrl
        }
      })
    }
  );
  
  return await response.json();
}

4. Recurring Payment / Subscription

Create checkout for recurring payments:

async function createSubscriptionCheckout(merchantId, subscriptionDetails) {
  const response = await fetch(
    'https://api.ahrvo.network/payments/na/checkout_forms',
    {
      method: 'POST',
      headers: {
        'Authorization': 'Basic ' + btoa('username:password'),
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        merchant_id: merchantId,
        payment_frequency: 'RECURRING',
        is_multiple_use: false,
        allowed_payment_methods: ['PAYMENT_CARD'],
        nickname: `${subscriptionDetails.planName} Subscription`,
        amount_details: {
          amount_type: 'FIXED',
          total_amount: subscriptionDetails.monthlyAmount,
          currency: 'USD'
        },
        items: [{
          name: subscriptionDetails.planName,
          description: subscriptionDetails.description,
          quantity: '1',
          price_details: {
            sale_amount: subscriptionDetails.monthlyAmount,
            currency: 'USD',
            price_type: 'REGULAR'
          }
        }],
        additional_details: {
          collect_name: true,
          collect_email: true,
          collect_billing_address: true,
          success_return_url: 'https://yoursite.com/subscription/success',
          terms_of_service_url: 'https://yoursite.com/terms'
        }
      })
    }
  );
  
  return await response.json();
}

5. Variable Amount Donation Form

Allow customers to enter their own amount:

async function createDonationForm(merchantId, causeInfo) {
  const response = await fetch(
    'https://api.ahrvo.network/payments/na/checkout_forms',
    {
      method: 'POST',
      headers: {
        'Authorization': 'Basic ' + btoa('username:password'),
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        merchant_id: merchantId,
        payment_frequency: 'ONE_TIME',
        allowed_payment_methods: ['PAYMENT_CARD', 'BANK_ACCOUNT'],
        nickname: 'Donation Form',
        amount_details: {
          amount_type: 'VARIABLE',
          min_amount: 500, // $5 minimum
          max_amount: 1000000, // $10,000 maximum
          currency: 'USD'
        },
        items: [{
          name: causeInfo.name,
          description: causeInfo.description,
          image_details: {
            primary_image_url: causeInfo.imageUrl
          }
        }],
        additional_details: {
          collect_name: true,
          collect_email: true,
          success_return_url: 'https://yoursite.com/donation/thank-you'
        }
      })
    }
  );
  
  return await response.json();
}

6. Marketplace Split Payment

Split payment across multiple merchants:

async function createMarketplaceCheckout(primaryMerchantId, cartItems) {
  // Calculate amounts for each vendor
  const vendorAmounts = {};
  let total = 0;
  
  cartItems.forEach(item => {
    const itemTotal = item.price * item.quantity;
    total += itemTotal;
    
    if (!vendorAmounts[item.vendorId]) {
      vendorAmounts[item.vendorId] = 0;
    }
    vendorAmounts[item.vendorId] += itemTotal;
  });
  
  // Platform fee (10%)
  const platformFee = Math.round(total * 0.10);
  
  const response = await fetch(
    'https://api.ahrvo.network/payments/na/checkout_forms',
    {
      method: 'POST',
      headers: {
        'Authorization': 'Basic ' + btoa('username:password'),
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        merchant_id: primaryMerchantId,
        payment_frequency: 'ONE_TIME',
        allowed_payment_methods: ['PAYMENT_CARD'],
        nickname: 'Marketplace Order',
        amount_details: {
          amount_type: 'FIXED',
          total_amount: total,
          currency: 'USD'
        },
        items: cartItems.map(item => ({
          name: item.name,
          description: `From ${item.vendorName}`,
          quantity: item.quantity.toString(),
          price_details: {
            sale_amount: item.price,
            currency: 'USD',
            price_type: 'REGULAR'
          }
        })),
        split_transfers: Object.entries(vendorAmounts).map(([vendorId, amount]) => ({
          merchant: vendorId,
          amount: amount - Math.round(amount * 0.10), // Vendor gets 90%
          fee: Math.round(amount * 0.10), // Platform keeps 10%
          tags: {
            order_type: 'marketplace',
            vendor_id: vendorId
          }
        })),
        additional_details: {
          collect_name: true,
          collect_email: true,
          collect_shipping_address: true,
          success_return_url: 'https://marketplace.com/order/success'
        }
      })
    }
  );
  
  return await response.json();
}

7. Checkout with Surcharge

Add surcharge for credit card processing:

async function createCheckoutWithSurcharge(merchantId, baseAmount) {
  const surchargeAmount = Math.round(baseAmount * 0.03); // 3% surcharge
  const total = baseAmount + surchargeAmount;
  
  const response = await fetch(
    'https://api.ahrvo.network/payments/na/checkout_forms',
    {
      method: 'POST',
      headers: {
        'Authorization': 'Basic ' + btoa('username:password'),
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        merchant_id: merchantId,
        payment_frequency: 'ONE_TIME',
        allowed_payment_methods: ['PAYMENT_CARD'],
        amount_details: {
          amount_type: 'FIXED',
          total_amount: total,
          currency: 'USD',
          amount_breakdown: {
            subtotal_amount: baseAmount,
            additional_buyer_charges: {
              surcharge_amount: surchargeAmount
            }
          }
        },
        additional_details: {
          collect_name: true,
          collect_email: true
        }
      })
    }
  );
  
  return await response.json();
}

8. Comprehensive Checkout Form

Full-featured checkout with all options:

async function createComprehensiveCheckout(config) {
  const response = await fetch(
    'https://api.ahrvo.network/payments/na/checkout_forms',
    {
      method: 'POST',
      headers: {
        'Authorization': 'Basic ' + btoa('username:password'),
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        merchant_id: config.merchantId,
        payment_frequency: config.paymentFrequency || 'ONE_TIME',
        is_multiple_use: config.multipleUse || false,
        allowed_payment_methods: config.paymentMethods || ['PAYMENT_CARD', 'BANK_ACCOUNT'],
        nickname: config.nickname,
        
        // Items
        items: config.items,
        
        // Amount details
        amount_details: {
          amount_type: config.amountType || 'FIXED',
          total_amount: config.totalAmount,
          currency: config.currency || 'USD',
          min_amount: config.minAmount,
          max_amount: config.maxAmount,
          amount_breakdown: {
            subtotal_amount: config.subtotal,
            shipping_amount: config.shipping,
            estimated_tax_amount: config.tax,
            discount_amount: config.discount,
            tip_amount: config.tip,
            additional_buyer_charges: {
              surcharge_amount: config.surcharge,
              convenience_amount: config.convenienceFee
            }
          }
        },
        
        // Branding
        branding: config.branding,
        
        // Additional details
        additional_details: {
          collect_name: config.collectName !== false,
          collect_email: config.collectEmail !== false,
          collect_phone_number: config.collectPhone || false,
          collect_billing_address: config.collectBilling || false,
          collect_shipping_address: config.collectShipping || false,
          success_return_url: config.successUrl,
          cart_return_url: config.cartUrl,
          expired_session_url: config.expiredUrl,
          terms_of_service_url: config.termsUrl,
          expiration_in_minutes: config.expirationMinutes || 10080
        },
        
        // Split transfers
        split_transfers: config.splitTransfers,
        
        // Tags
        tags: config.tags
      })
    }
  );
  
  const form = await response.json();
  
  // Log important details
  console.log('Checkout Form Created:', {
    id: form.id,
    url: form.link_url,
    expires: form.link_expires_at,
    state: form.state
  });
  
  return form;
}

Request Parameters

Required Fields

Parameter	Type	Description
merchant_id	string	ID of the merchant
payment_frequency	string	ONE_TIME or RECURRING
allowed_payment_methods	array	Array of PAYMENT_CARD and/or BANK_ACCOUNT

Optional Fields

Parameter	Type	Description
is_multiple_use	boolean	Whether form can be used multiple times
nickname	string	Friendly name for the checkout form
items	array	Products or services being sold
amount_details	object	Pricing information
branding	object	Custom branding (colors, logo)
additional_details	object	Form behavior and data collection settings
split_transfers	array	Marketplace payment splits
tags	object	Custom metadata

Response Fields

Field	Type	Description
id	string	Unique checkout form ID
created_at	string	Creation timestamp
link_url	string	The URL to send customers to
link_expires_at	string	When the link expires
state	string	Form state (typically ACTIVE)
merchant_id	string	Associated merchant
application_id	string	Associated application
payment_frequency	string	Payment type
allowed_payment_methods	array	Allowed payment methods

Best Practices

1. Always Store the Checkout URL

The link_url is what you send to customers:

const form = await createBasicCheckoutForm(merchantId, 5000);

// Store this URL in your database
await saveCheckoutLink({
  order_id: orderId,
  checkout_form_id: form.id,
  checkout_url: form.link_url,
  expires_at: form.link_expires_at
});

// Send to customer
await sendEmail(customerEmail, {
  subject: 'Complete Your Purchase',
  checkout_link: form.link_url
});

2. Set Appropriate Expiration Times

Default is 7 days (10080 minutes), adjust as needed:

// Short expiration for flash sales
expiration_in_minutes: 60 // 1 hour

// Extended for invoices
expiration_in_minutes: 43200 // 30 days

3. Use Success URLs for Order Confirmation

Always set a success return URL:

additional_details: {
  success_return_url: `https://yoursite.com/order/${orderId}/success`,
  cart_return_url: `https://yoursite.com/cart/${cartId}`,
  expired_session_url: 'https://yoursite.com/checkout/expired'
}

4. Collect Necessary Information Only

Don't ask for more than you need:

// Minimal for digital products
additional_details: {
  collect_name: true,
  collect_email: true,
  collect_phone_number: false,
  collect_billing_address: false,
  collect_shipping_address: false
}

// Full details for physical products
additional_details: {
  collect_name: true,
  collect_email: true,
  collect_phone_number: true,
  collect_billing_address: true,
  collect_shipping_address: true
}

5. Brand Your Checkout

Maintain consistent branding:

branding: {
  brand_color: '#YOUR_PRIMARY_COLOR',
  accent_color: '#YOUR_ACCENT_COLOR',
  button_font_color: '#FFFFFF',
  logo: 'https://yoursite.com/logo.png',
  logo_alternative_text: 'Your Company Name'
}

6. Use Descriptive Nicknames

Help identify forms in your dashboard:

nickname: `Order #${orderId} - ${customerName}`,
// or
nickname: `${subscriptionPlan} - ${customerEmail}`,
// or
nickname: `Invoice ${invoiceNumber}`

7. Tag Everything

Use tags for tracking and reporting:

tags: {
  order_id: orderId,
  customer_id: customerId,
  campaign: 'summer_sale_2025',
  source: 'email_marketing',
  product_category: 'electronics'
}

8. Handle Errors Gracefully

Always handle creation errors:

async function safeCreateCheckout(config) {
  try {
    const response = await fetch(
      'https://api.ahrvo.network/payments/na/checkout_forms',
      {
        method: 'POST',
        headers: {
          'Authorization': 'Basic ' + btoa('username:password'),
          'Content-Type': 'application/json'
        },
        body: JSON.stringify(config)
      }
    );
    
    if (!response.ok) {
      const error = await response.json();
      throw new Error(`Checkout creation failed: ${error._embedded?.errors?.[0]?.message || 'Unknown error'}`);
    }
    
    return await response.json();
    
  } catch (error) {
    console.error('Error creating checkout form:', error);
    
    // Notify admins
    await alertAdmins('Checkout form creation failed', {
      config,
      error: error.message
    });
    
    throw error;
  }
}

Common Workflows

E-Commerce Order Flow

async function processEcommerceOrder(cart, customer) {
  // 1. Calculate totals
  const subtotal = cart.items.reduce((sum, item) => sum + (item.price * item.quantity), 0);
  const shipping = calculateShipping(cart.items, customer.address);
  const tax = calculateTax(subtotal, customer.address);
  const total = subtotal + shipping + tax;
  
  // 2. Create checkout form
  const form = await createProductCheckout(merchantId, cart.items);
  
  // 3. Store checkout reference
  await db.orders.create({
    order_id: generateOrderId(),
    customer_id: customer.id,
    checkout_form_id: form.id,
    checkout_url: form.link_url,
    amount: total,
    status: 'PENDING_PAYMENT',
    expires_at: form.link_expires_at
  });
  
  // 4. Send to customer
  await sendEmail(customer.email, {
    subject: 'Complete Your Order',
    template: 'checkout_link',
    data: {
      checkout_url: form.link_url,
      order_summary: cart.items,
      total: `$${(total / 100).toFixed(2)}`
    }
  });
  
  return form;
}

Subscription Signup

async function initiateSubscription(plan, customer) {
  const form = await createSubscriptionCheckout(merchantId, {
    planName: plan.name,
    description: plan.description,
    monthlyAmount: plan.price
  });
  
  // Store subscription intent
  await db.subscriptions.create({
    customer_id: customer.id,
    plan_id: plan.id,
    checkout_form_id: form.id,
    status: 'PENDING_SETUP',
    created_at: new Date()
  });
  
  // Redirect customer to checkout
  return form.link_url;
}

Interactive API Reference