API Reference

2. Generating Payment Links

In the evolving digital payments landscape, Ping Payments offers a streamlined and efficient way to handle transactions through the generation of payment links. This comprehensive guide outlines the process of creating and utilizing payment links within the Ping Payments system, detailing the prerequisites for successful integration and the steps to effectively implement payment links. Whether you're a seasoned developer or new to the Ping Payments platform, this guide will provide you with the necessary knowledge and tools to enhance your payment processing capabilities.

Prerequisites

Before generating payment links with Ping Payments, ensure the following prerequisites are met:

  • Tenant Onboarding:
    Ensure you are onboarded as a tenant with Ping Payments, possessing a valid tenant_id and API credentials.
  • Merchant Registration
    Register your merchants using the Create Merchant endpoint.
  • Payment Method Activation
    Have either Swish or Card payments (or other relevant methods) activated on your tenant. Your activated payment provider methods can be verified through the Get Tenant endpoint.

Creating a Payment Order

Firstly, create a payment order using the Create Payment Order endpoint. This step initiates the transaction process and is essential for generating payment links.

Understanding Payment Links

  • Multiple Links per Order
    A single payment order can encompass several different payment links, catering to various payment scenarios.
  • Acquisition of Funds
    Payment links facilitate the acquisition of funds through the Ping Checkout or by paying the invoice generated via the Create Payment Link Invoice endpoint.

The Payment Links Object

The Payment Links object is a JSON structure that specifies the details of the transaction. Here is an example:

{
  "currency": "{{ currency }}",
  "customer": {
    "first_name": "Kalle",
    "last_name": "Karlsson",
    "email": "[email protected]",
    "phone": "07012345678"
  },
  "delivery_address": {
    "city": "Örebro",
    "street_address": "Nygatan 15",
    "zip": "702 10"
  },
  "due_date": "2024-12-25",
  "invoice_address": {
    "city": "Örebro",
    "street_address": "Nygatan 15",
    "zip": "702 10"
  },
  "items": [
    {
      "description": "Membership",
      "merchant_id": "{{ merchant_id }}",
      "price": 10000,
      "quantity": 1,
      "vat": 25
    },
      {
      "description": "Club T-shirt",
      "merchant_id": "{{ merchant_id }}",
      "price": 20000,
      "quantity": 2,
      "vat": 25
    },
    {
      "description": "Administration Fee",
      "merchant_id": "{{ merchant_id }}",
      "price": 5000,
      "quantity": 1,
      "vat": 0
    }
  ],
  "metadata": {
    "checkout_settings": {
      "summary_settings": {
        "visible": true,
        "visible_headline": true,
        "display_price_including_vat": true,
        "show_vat_row_for_each_item": true,
        "hide_vat_if_zero_vat": false,
        "show_total_summary": true,
        "show_total_vat_summary": true,
        "index": 2,
        "collapsed": false,
        "supplier_settings": {
          "visible": true,
          "collapsed": true
        }
      },
      "payer_information_settings": {
        "visible": true,
        "index": 0
      },
      "payment_method_settings": {
        "index": 1,
        "preselected_payment_method": {
          "provider": "payment_iq",
          "method": "card"
        }
      },
      "display_mode": "box"
    }
  },
  "locale": "sv-SE",
  "logo_image_link": "https://pingpayments.com/logo.png",
  "payment_link_status_callback_url": "https://someurl.com/payment_link_callback",
  "payment_order_id": "{{ payment_order_id }}",
  "payment_provider_methods": [
    {
      "method": "card",
      "provider": "payment_iq"
    },
    {
      "method": "m_commerce",
      "provider": "swish",
      "parameters": {
        "swish_message": "Tack för ditt köp!"
      }
    }
  ],
  "supplier": {
    "name": "Ping Sportsclub AB",
    "city": "Örebro",
    "email": "[email protected]",
    "organization_number": "5555-123456",
    "phone_number": "0709995544",
    "street": "Signalgatan 9",
    "website": "pingsportsclub.com",
    "zip": "702 25"
  },
  "total_amount": 55000
}

Key Components of the Payment Links Object:

  • Customer and Address Information
    Includes details like name, email, phone number, and address.
  • Items
    An array of items being purchased, with details such as description, price, quantity, and VAT.
  • Metadata
    Contains checkout_settings to customize the checkout experience. You can read more about this in the previous chapter.
  • Payment Providers and Methods
    Specifies the payment methods and providers, including any specific parameters like messages for Swish transactions.
  • payment_link_status_callback_url
    This URL is crucial for receiving callbacks regarding the status of the payment link. When the status of a payment link changes (e.g., from pending to paid), a callback is sent to this URL, enabling real-time updates in your system as a Tenant integrator.