Checkout

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude

Checkout is easypay's integrated solution for collecting payments in any website with minimal development effort.

Overview

Checkout is a pre-built payment form that you can embed directly into your website. It handles the entire payment flow including:

• Collecting customer information
• Payment method selection
• Payment information collection
• Invoking payment APIs
• Displaying payment feedback

Key Benefits

• No extensive programming required: Embed with just a few lines of code
• All payment methods supported: Credit cards, MB WAY, Apple Pay, Google Pay, Samsung Pay, Multibanco, Direct Debit, Virtual IBAN
• All payment types supported: Single, Frequent, and Subscription payments
• Fully customizable: Match your brand with extensive styling options
• Mobile responsive: Works seamlessly on all devices
• Multiple integration methods: Script tag or NPM package

Live Demo

Explore the live Checkout demo to see the solution in action and try different payment flows.

View the source code on GitHub with instructions for running locally.

How It Works

1. Create a Checkout Session (Server-Side)

Make a server-to-server POST request to create a checkout session:

curl -X POST 'https://api.test.easypay.pt/2.0/checkout' \
  -H 'AccountId: YOUR_ACCOUNT_ID' \
  -H 'ApiKey: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": ["single"],
    "payment": {
      "methods": ["cc", "mb", "mbw", "dd", "vi"],
      "type": "sale",
      "currency": "EUR"
    },
    "order": {
      "items": [
        {
          "description": "T-shirt",
          "quantity": 1,
          "key": "t-shirt",
          "value": 12.50
        }
      ],
      "key": "order-123",
      "value": 12.50
    }
  }'

Response:

{
  "id": "57cc19e9-f393-4cfa-9516-8807763b5096",
  "session": "8zoaBOC0Mj5Mg_YAbdRCqY...",
  "config": null
}

This response is called the Checkout manifest.

2. Display the Checkout Form (Client-Side)

Option A: Script Tag (Simplest)

<!-- Include the SDK -->
<script src="https://cdn.easypay.pt/checkout/2.9.1/"></script>

<!-- Prepare a container -->
<div id="easypay-checkout"></div>

<script>
  // Get the manifest from your server
  const manifest = await getManifestFromServer();

  // Initialize Checkout
  easypayCheckout.startCheckout(manifest);
</script>

Option B: NPM Package

npm install --save @easypaypt/checkout-sdk

import { startCheckout } from "@easypaypt/checkout-sdk";

const manifest = await getManifestFromServer();
startCheckout(manifest);

Common Use Cases

Single Payment

For one-time purchases:

{
  "type": ["single"],
  "payment": {
    "methods": ["cc", "mbw", "mb"],
    "type": "sale",
    "currency": "EUR"
  },
  "order": {
    "items": [
      { "description": "Product", "quantity": 1, "value": 29.99 }
    ],
    "value": 29.99
  }
}

Frequent Payment (Tokenization)

To save payment details for future use:

{
  "type": ["frequent"],
  "payment": {
    "methods": ["cc", "mbw", "dd"],
    "currency": "EUR"
  }
}

Handle the success callback to get the payment ID:

startCheckout(manifest, {
  onSuccess: (checkoutInfo) => {
    // Save checkoutInfo.payment.id for later captures
    saveTokenToServer(checkoutInfo.payment.id);
  }
});

Later, capture funds using the saved ID:

POST /capture/:id
{
  "value": 50.00,
  "descriptive": "Purchase in MyStore"
}

Subscription Payment

For recurring payments:

{
  "type": ["subscription"],
  "payment": {
    "methods": ["cc", "dd"],
    "type": "sale",
    "frequency": "1M",
    "start_time": "2024-02-01 00:00",
    "max_captures": 12
  },
  "order": {
    "items": [
      { "description": "Monthly Subscription", "value": 9.99 }
    ],
    "value": 9.99
  }
}

Advanced Features

Display Modes

Inline Mode (default): Embeds the checkout form in your page

startCheckout(manifest, {
  display: "inline"
});

Popup Mode: Opens checkout in a popup/modal

<button id="checkout-button">Pay Now</button>

<script>
easypayCheckout.startCheckout(manifest, {
  id: "checkout-button",
  display: "popup"
});
</script>

Event Handlers

React to payment events:

startCheckout(manifest, {
  onSuccess: (checkoutInfo) => {
    console.log('Payment successful:', checkoutInfo);
    // checkoutInfo contains payment details, method, status, etc.
  },

  onError: (error) => {
    console.error('Unrecoverable error:', error);
    if (error.code === 'checkout-expired') {
      // Create new session
    }
  },

  onPaymentError: (error) => {
    console.log('Recoverable payment error:', error);
    // User can retry
  },

  onClose: () => {
    console.log('Checkout closed');
    // Clean up or redirect
  }
});

Customization

Match your brand with extensive styling options:

startCheckout(manifest, {
  logoUrl: "https://yoursite.com/logo.png",
  accentColor: "#FF6B35",
  backgroundColor: "#F7F7F7",
  buttonBackgroundColor: "#FF6B35",
  buttonBorderRadius: 5,
  inputBorderRadius: 5,
  fontFamily: "Arial, sans-serif",
  baseFontSize: 12
});

Example customization:

Available customization options:

• Company logo
• Background colors
• Accent colors
• Button colors and styles
• Input field colors and styles
• Font family and size
• Border radius
• Box shadows

Testing

To test without real transactions:

startCheckout(manifest, {
  display: "inline",
  testing: true  // Use test environment
});

Important:

• Create sessions using https://api.test.easypay.pt
• Use test payment methods (see Payment Methods guide)
• Remove testing: true when going to production

Managing Checkout Instance

Store the instance for later management:

const checkoutInstance = startCheckout(manifest, {
  onSuccess: (info) => {
    // Payment successful, clean up
    checkoutInstance.unmount();
    showThankYouMessage();
  }
});

// Later, manually remove checkout
checkoutInstance.unmount();

Session Expiration

Checkout sessions expire after 30 minutes. Handle expiration gracefully:

startCheckout(manifest, {
  onError: async (error) => {
    if (error.code === 'checkout-expired') {
      // Create a new session
      const newManifest = await createNewSession();
      startCheckout(newManifest);
    }
  }
});

Error Codes

Supported Languages

Checkout automatically detects the user's browser language, but you can override it:

startCheckout(manifest, {
  language: "pt_PT"  // Portuguese
  // Options: "en", "pt_PT", "es_ES"
});

Best Practices

1. Always Create Sessions Server-Side: Never expose your API keys in client code
2. Handle All Error Cases: Implement error handlers for better UX
3. Use Webhooks: Don't rely solely on client-side success callbacks for critical logic
4. Test Thoroughly: Use the test environment extensively before going live
5. Customize for Your Brand: Match Checkout to your website's look and feel
6. Mobile First: Test on various devices and screen sizes
7. Verify Payments: Always verify payment status on your server using the API

SDK Reference

startCheckout(manifest, [options])

Parameters:

• manifest: The return object from the checkout service.
• options: An optional object containing any of the following properties:

Options

(1) display available values: inline (default) or popup.

(2) language available values: en (English), pt_PT (Portuguese) or es_ES (Spanish). If left undefined, a default language will be selected according to the customer's browser language.

Return:

• A CheckoutInstance object, containing the following method:
  • unmount(): Removes all Checkout form content and event listener.

Success handler

onSuccess(checkoutInfo)

Receives an object with the following properties:

Properties of the payment Object:

Note: Some properties only appear with certain payment methods.

(1) Possible method values are the same as in the Checkout creation.

(2) Possible payment status values:

(3) Format of the expiration varies between Credit Card ('MM/YY' format) and Multibanco ('Y-m-d H:i').

(4) Properties of the sddMandate Object:

Error handler:

onError(error)

Receives an object with the following property:

The error code has the following possible values and recommended solutions:

Payment error handler

onPaymentError(error)

Signals the occurrence of a recoverable error during a payment attempt. These errors are informative and for logging/analysis purposes, as the user is allowed (and encouraged) to try the payment again with the same or other payment method.

Receives an object with the following properties:

The error code has the following possible values and recommended solutions:

Next Steps

• Checkout API Reference - Complete API documentation
• Webhooks Guide - Receive payment notifications
• Payment Methods - Learn about available payment methods
• Payment Types - Understand Single, Frequent, and Subscription payments
• GitHub Demo - Full working example