Accept Payments via Payment Links

📘 1. Overview

Apcopay’s Payment Link feature allows merchants to generate shareable links that redirect customers to a secure, Apcopay‑hosted payment page.

• CreatePaymentLink: Register and configure a new link with associated transaction parameters.
• GetPaymentLinks: Retrieve details about an existing payment link by token.

Use Payment Links when you want to accept payments without building a full checkout flow or wanting on‑demand payment requests via email, SMS, QR code, etc. (apcopay.redoc.ly)

2. Key Attributes & When to Use Them

2.1 TransactionType

• "AUTH": authorize only (funds not captured)
• "PURC": full purchase (authorize + capture)
  Use case: Select "AUTH" if you want to review or capture later; otherwise "PURC" for immediate payment. (apcopay.redoc.ly)

2.2 OrderReference

Merchant’s unique identifier for reconciliation (e.g. "INV‑20250710‑001"). Always required.

2.3 Currency & Amount

• Currency: ISO 4217 code (e.g. "EUR", "USD"). Required.
• Amount: transaction total. Optional—when omitted, link permits customer‑entered amount (e.g. donations). As amount of 0 is allowed in the context of new card registration in the context of MITs or recurring payment scenarios (apcopay.redoc.ly)

2.4 CallBackURL

Webhook notification endpoint – Apcopay will POST payment status updates here.

2.5 Language

ISO 639‑1 language code (“en” default). Sets UI language on landing page.

2.6 IsTest

Boolean. If true, link will operate in sandbox/test mode. Omit or false for production.

2.7 Client object

Contains payer details: Email, ClientAccount, FirstName/LastName, Country, MobileNo, Address, IPAddress, etc. Required. (apcopay.redoc.ly)

2.8 UDF (User‑Defined Fields)

Arbitrary key/value data for internal tracking (e.g. payment iteration, internal reference). Optional.

2.9 Configuration.PaymentLink

The Configration node contains nested configuration controlling link behavior:

• ExecutionBehaviour: enable/disable, one‑time use vs reusable, recurring, valid time window (Epoch timestamps), SendEmailOnCreate, admin & event recipient emails.
• UIBehaviour: ShowTermsAndConditions, ShowClientInfo, AllowClientEdit flags. (apcopay.redoc.ly)

2.9.1 PaymentLink.ExecutionBehaviour

The ExecutionBehaviour node defines the lifecycle, reusability, and validity window of the payment link. It ensures the link behaves according to business, regulatory, or operational constraints.

JSON Path

Configuration: {
  PaymentLink: {
    ExecutionBehaviour: {
      ...
    }
  }
}

🔧 Key Attributes Information

✅ Example

"ExecutionBehaviour": {
  "IsEnabled": true,
  "OneTimeUse": true,
  "IsRecurring": false,
  "ValidFrom": 1718908800,
  "ValidUntil": 1718908899
}

This setup defines a link that:

• Is active (IsEnabled: true)

• Can only be used once

• Is not recurring

• Is valid only between:

  • 1718908800 → 2024-06-20 00:00:00 UTC
  • 1718908899 → 2024-06-20 00:01:39 UTC (99 seconds of validity)

📌 Behavior Notes

• IsEnabled = false: disables the link immediately, regardless of time window.

• OneTimeUse = true: link is consumed after the first successful transaction.

• IsRecurring = true: indicates intent to tokenize card details for future use.

• ValidFrom and ValidUntil provide a strict activation window. Outside this range:

  • Customer sees an expired/invalid link message.
  • No redirection to payment page occurs.

🛡️ Security & Business Scenarios

🔒 Operational Guardrails

• Implement a cron or webhook listener to deactivate expired links if needed.
• Be cautious of timezone offsets when calculating ValidFrom/Until.
• Re-enable or regenerate links programmatically if expiration windows lapse before payment is completed.

Let me know if you’d like to add validation logic, best practice enforcement, or a Mermaid sequence diagram showing link expiry behavior.

2.9.2 PaymentLink.UIBehaviour

The UIBehaviour object defines how the customer-facing Apcopay Payment Link Page will be presented to the end-user. It allows merchants to configure the visibility, interactivity, and compliance elements of the page experience.

JSON Path

Configuration: {
  PaymentLink: {
    UIBehaviour: {
      ...
    }
  }
}

🔧 Key Attributes Information

✅ Example

"UIBehaviour": {
  "ShowTermsAndConditions": true,
  "ShowClientInfo": true,
  "AllowClientEdit": false
}

This will:

• Display the Terms checkbox (must be checked to proceed),
• Pre-fill the payment page with client details (read-only),
• Prevent customers from modifying their details.

💡 Behavior Notes

• If ShowClientInfo = false, the customer sees a minimal checkout page (client identity omitted).
• If AllowClientEdit = true and ShowClientInfo = true, the page renders editable fields (e.g. email, phone).
• Use AllowClientEdit = false in regulated scenarios where payer info must remain merchant-defined (e.g. invoice, pay-by-link for services rendered).
• ShowTermsAndConditions = true is often recommended for GDPR/PCI compliance, especially in EU jurisdictions.

🔒 Compliance Tip

Use:

"ShowTermsAndConditions": true

to ensure legal consent capture for payment authorization, particularly when links are public or shared.

3. Sequence Flow

4. API Request & Response: Technical Reference

4.1 Create Payment Link (POST /api/paymentlinks)

Request Body Snapshot :

{
  "TransactionType": "AUTH",
  "BrandCode": "7781",
  "OrderReference": "OrderRef158753",
  "Currency": "EUR",
  "Amount": 0,
  "CallBackURL": "https://yourURLhere.com/notification/",
  "Language": "en",
  "IsTest": true,
  "Client": {
    "Email": "joe.bloggs@testjb.com",
    "ClientAccount": "CliAcc01002",
    "FirstName": "Joe",
    "LastName": "Bloggs",
    "Country": "MLT",
    "MobileNo": "00441234567",
    "Street": "High Street",
    "City": "MagicCity",
    "ZIPCode": "BGGC1234",
    "State": "UK",
    "DateOfBirth": "2924-12-31",
    "IPAddress": "214.21.134.79"
  },
  "UDF": {
    "PaymentIteration": "20240228-01",
    "InternalReference": "EXC020120112"
  },
  "Configuration": {
    "PaymentLink": {
      "ExecutionBehaviour": {
        "IsEnabled": true,
        "OneTimeUse": true,
        "IsRecurring": false,
        "ValidFrom": 1718908800,
        "ValidUntil": 1718908899,
        "SendEmailOnCreate": true,
        "AdminEmails": [
          "admin1@mycompany.eu, admin2@mycompany.us"
        ],
        "LinkEventRecipientEmail": [
          "abc.def@mailer.me",
          "abc.ghj@mailer.me"
        ]
      },
      "UIBehaviour": {
        "ShowTermsAndConditions": true,
        "ShowClientInfo": false,
        "AllowClientEdit": false
      }
    }
  }
}

Response :

{
  "PaymentLinkToken": "f86dff7b36aa4401bbb92c88280d6db4",
  "PaymentLinkUrl": "https://payments.link.apcopay.tech/Loader?token=f86dff7b36aa4401bbb92c88280d6db4",
  "IsSuccess": true,
  "ErrorMessage": ""
}

4.2 Get Payment Link (GET /api/paymentlinks?PaymentLinkToken=...)

Response includes full configuration/status (ExecutionBehaviour, UIBehaviour, Client, UDF, etc.) .

5. Business Use Cases

Use Case A: One‑off invoice payment via email

• Invoice issued → merchant system calls CreatePaymentLink with "PURC", fixed Amount, one‑time use (OneTimeUse: true), SendEmailOnCreate: false.
• Link emailed via merchant platform → customer pays → webhook confirms success → system marks invoice paid.

Use Case B: Charity donation portal

• Public “Donate” page calls CreatePaymentLink with Amount: 0, omitted amount enables donor to input.
• No OneTimeUse, ShowClientInfo: true to capture name/email.
• Success webhook triggers thank‑you email + tax receipt.

Use Case C: Recurring payment authorization

• For periodic billing model: TransactionType: "AUTH", maybe configurable ValidUntil far in future.
• Each authorized link can then be captured later via a DirectConnect transaction flow or else via Auto Capture functionality - talk to our support team for setup.

Use Case D: New Card Registration for Recurring Payments

• For new card registration: TransactionType: "AUTH", IsRecurring: false, Amount: 0,maybe configurable ValidUntil based on dunning model.
• Once transaction of 0 Amount is processed new CardToken and PspID are picked up from the webhook call endpoint configured in the request.

6. Integration Tips & Best Practices

• Always use unique OrderReference and UniqueReference for idempotency and audit trail.
• Use IsTest=true during integration & QA, then set to false in production.
• Validate incoming webhook signature (HMAC algorithm shared with Apcopay) before acting.
• Use Configuration.ExecutionBehaviour.OneTimeUse and ValidUntil to restrict reuse of links.

7. Validation & Error Handling

• API will return standard HTTP codes.
• If IsSuccess: false, ErrorMessage provides diagnostic hints.
• Use GetPaymentLink to verify a link's lifecycle: active, expired, disabled.

8. Troubleshooting Scenarios

🔚 Summary

• Payment Link API is ideal when you need lightweight, shareable payment requests.
• Use structured fields like TransactionType, Client, and Configuration to tailor link behavior.
• Use Create to generate, Get to inspect, and webhook notifications for transaction completion.
• Business cases range from invoicing, repeat authorization, charity, phone‑order collections, etc.