--- title: "Create a Fast Link" slug: "accept-payments-via-payment-links" updated: 2025-07-09T14:54:19Z published: 2025-07-09T14:54:19Z canonical: "docs.apcopay.com/accept-payments-via-payment-links" --- > ## Documentation Index > Fetch the complete documentation index at: https://docs.apcopay.com/llms.txt > Use this file to discover all available pages before exploring further. # 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][1]) --- ## 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][1]) :::(Info) (AUTH - Auto Capturing) Merchants that use the AUTH based payment link typically configure the auto CAPTURE scheduler capability. Speak to our support for more information about setting this up. ::: ### 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][1]) ### 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][1]) ### 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][1]) #### 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 ```json Configuration: { PaymentLink: { ExecutionBehaviour: { ... } } } ``` --- ### šŸ”§ Key Attributes Information | Field | Type | Description | | ------------- | --------------- | ----------------------------------------------------------------------------------------------------------------------- | | `IsEnabled` | Boolean | Enables or disables the payment link. If `false`, the link becomes inactive and will not load the payment page. | | `OneTimeUse` | Boolean | If `true`, the payment link can be used only once. After one completed transaction, it is invalidated automatically. | | `IsRecurring` | Boolean | Indicates whether the payment is part of a recurring transaction flow. Useful for subscriptions or token-based billing. | | `ValidFrom` | Integer (Epoch) | Defines the start time (in UTC Unix timestamp) from which the link becomes usable. | | `ValidUntil` | Integer (Epoch) | Defines the end time (in UTC Unix timestamp) after which the link expires. | --- ### āœ… Example ```json "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 | Use Case | Recommended Settings | | ------------------------------------------------ | -------------------------------------------------------------------------- | | Single-use invoice payment | `OneTimeUse: true`, `ValidFrom/Until` for short time range | | Payment campaign (24h window) | `IsEnabled: true`, set `ValidFrom/Until` to span 1 day | | Subscription opt-in | `IsRecurring: true`, link enabled until customer activates | | Temporary service access (e.g., pay-to-download) | Use `OneTimeUse: true`, and set `ValidUntil` shortly after link generation | --- ### šŸ”’ 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 ```json Configuration: { PaymentLink: { UIBehaviour: { ... } } } ``` --- ### šŸ”§ Key Attributes Information | Field | Type | Description | | ------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------- | | `ShowTermsAndConditions` | Boolean | If `true`, displays a "Terms and Conditions" checkbox (mandatory to continue). | | `ShowClientInfo` | Boolean | If `true`, displays the clientā€™s information (from the `Client` object) in read-only form. | | `AllowClientEdit` | Boolean | If `true`, allows the customer to edit their personal details (name, email, address, etc.) before submitting the payment. | --- ### āœ… Example ```json "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: ```json "ShowTermsAndConditions": true ``` to ensure legal consent capture for payment authorization, particularly when links are public or shared. --- ## 3. Sequence Flow ![image.png](https://cdn.document360.io/358ada76-9dff-4d31-80ba-dad90c84bfa9/Images/Documentation/image%2838%29.png){height="" width=""} --- ## 4. API Request & Response: Technical Reference ### 4.1 Create Payment Link (POST `/api/paymentlinks`) **Request Body Snapshot** : ```json { "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** : ```json { "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 | Symptom | Root Cause | Recommended Action | | ---------------------------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------- | | Customer reports page not accessible | Link expired or `IsEnabled=false` | Retrieve via GET, check ExecutionBehaviour.IsEnabled OR ExecutionBehaviour.ValidFrom OR ExecutionBehaviour.ValidUntil; recreate link if needed | | Unrecognized `CallBackURL` payload | Signature validation failed | Verify HMAC implementation and keys match | --- ## šŸ”š 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. [1]: https://apcopay.redoc.ly/?utm_source=chatgpt.com "Apcopay Synthesis (0.3.0) - Redocly"