> For the complete documentation index, see [llms.txt](https://plexo.gitbook.io/rest-api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://plexo.gitbook.io/rest-api/payment-links/integration-guide.md).

# Integration Guide

This guide walks you through integrating Payment Links into your application, from initial setup to handling payment notifications.

## Prerequisites

Before you begin, ensure you have:

1. **API credentials** — A username and password for Basic Auth, or a Bearer Token. See [Authentication](/rest-api/getting-started/authentication.md).
2. **A merchant** — At least one merchant configured in your Plexo account. See [Merchant Management](/rest-api/merchant-configuration/merchant-management.md).
3. **Payment methods** — At least one payment method enabled for your merchant. See [Payment Methods Setup](/rest-api/merchant-configuration/payment-methods-setup.md).
4. **A callback endpoint** — A publicly accessible URL to receive payment notifications (recommended but optional).

## Integration flow

```mermaid
sequenceDiagram
  participant Merchant as Your backend
  participant Plexo as Plexo API
  participant Checkout as Plexo Hosted Checkout
  participant Payer as Payer

  Merchant->>Plexo: POST /v1/payment-links (create link)
  Plexo-->>Merchant: PaymentLinkDto with externalId
  Merchant->>Payer: Share link URL (email, SMS, QR, etc.)
  Payer->>Checkout: Opens link URL
  Checkout->>Plexo: Resolve link & create session (internal)
  Checkout-->>Payer: Hosted checkout page
  Payer->>Checkout: Enters payment details & confirms
  Checkout->>Plexo: Process payment
  Plexo-->>Checkout: Payment result
  Checkout-->>Payer: Confirmation page
  Plexo-->>Merchant: Payment callback notification
```

The merchant's integration is limited to two steps: **create the link** and **handle the callback**. Plexo's hosted checkout handles the entire payer experience — no frontend code required.

## Step 1: Configure merchant settings

Before creating Payment Links, configure your merchant's default settings. This is optional but recommended — it sets defaults for currency, expiration, and callback URL.

```bash
curl -X PUT "https://api.plexo.com.uy/v1/payment-links/settings" \
  -u "YOUR_USERNAME:YOUR_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantId": 12345,
    "defaultExpirationMinutes": 1440,
    "defaultCurrency": "UYU",
    "notificationUrl": "https://yourapp.example.com/webhooks/plexo",
    "businessUrlName": "your-business",
    "quickPayEnabled": true
  }'
```

{% hint style="info" %}
The `notificationUrl` in merchant settings is the fallback callback URL. You can override it per-link using `settings.callbackUrl` when creating a Payment Link.
{% endhint %}

## Step 2: Create a Payment Link

Create a Payment Link by calling `POST /v1/payment-links` with the desired configuration.

### Fixed-amount link (regular)

```bash
curl -X POST "https://api.plexo.com.uy/v1/payment-links" \
  -u "YOUR_USERNAME:YOUR_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantId": 12345,
    "type": "regular",
    "amount": {
      "currency": "UYU",
      "total": 1500.00
    },
    "settings": {
      "amountMode": "fixed",
      "paymentMethods": ["VISA", "MASTERCARD"],
      "installments": { "*": [1, 3, 6] },
      "callbackUrl": "https://yourapp.example.com/webhooks/plexo",
      "skipPreCheckout": false
    },
    "items": [
      { "name": "Consulting — July 2025", "quantity": 1, "price": 1500.00 }
    ],
    "validUntil": "2025-08-01T00:00:00Z",
    "displayName": "Invoice #1042",
    "description": "Payment for consulting services"
  }'
```

### Flexible-amount link (one-time)

```bash
curl -X POST "https://api.plexo.com.uy/v1/payment-links" \
  -u "YOUR_USERNAME:YOUR_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantId": 12345,
    "type": "one-time",
    "settings": {
      "amountMode": "flexible",
      "paymentMethodTypes": ["card"],
      "flexibleAmount": {
        "minAmount": 100.00,
        "maxAmount": 50000.00,
        "suggestedAmount": 1000.00,
        "allowedCurrencies": ["UYU", "USD"]
      }
    },
    "displayName": "Donation",
    "description": "Support our cause"
  }'
```

The response includes the `externalId` you use to build the shareable URL:

```json
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "externalId": "pl_xK9mQ2vR",
  "merchantId": 12345,
  "type": "regular",
  "amount": {
    "currency": "UYU",
    "total": 1500.00,
    "details": null
  },
  "settings": {
    "amountMode": "fixed",
    "paymentMethodTypes": null,
    "paymentMethods": ["VISA", "MASTERCARD"],
    "installments": { "*": [1, 3, 6] },
    "callbackUrl": "https://yourapp.example.com/webhooks/plexo",
    "flexibleAmount": null,
    "skipPreCheckout": false
  },
  "validFrom": null,
  "validUntil": "2025-08-01T00:00:00Z",
  "displayName": "Invoice #1042",
  "description": "Payment for consulting services",
  "status": "active",
  "createdAt": "2025-07-01T14:30:00Z",
  "updatedAt": null,
  "splitDestinations": null
}
```

## Step 3: Share the link

Build the shareable URL using the `externalId` from the response:

```
https://links.plexo.com.uy/{externalId}
```

Distribute it to your payers through any channel:

* **Email** — Include the link in invoices or payment reminders.
* **SMS / WhatsApp** — Send the URL directly in a message.
* **QR Code** — Generate a QR code from the URL for in-person payments.
* **Website** — Embed the link as a button or hyperlink.

When a payer opens the link, Plexo displays a branded pre-checkout page with the merchant name, amount, description, and items. The payer clicks "Pay now" and is redirected to the Plexo checkout to enter payment details.

{% hint style="info" %}
**Skip the pre-checkout page** — If you prefer instant redirect to checkout (no landing page), set `settings.skipPreCheckout: true` when creating the link. This is useful for links embedded in your own UI where context is already provided.
{% endhint %}

## Step 4: Handle payment callbacks

When a payer completes a payment through your link, Plexo sends a POST request to your callback URL with the payment result.

Your callback endpoint should:

1. Verify the callback authenticity (see [Callbacks Guide](/rest-api/operations/callbacks.md)).
2. Process the payment result (mark orders as paid, send confirmations, etc.).
3. Return a `200 OK` response to acknowledge receipt.

{% hint style="warning" %}
If your callback endpoint is unreachable or returns an error, Plexo will retry the notification. Always return `200 OK` after processing, even if your business logic encounters an issue you handle asynchronously.
{% endhint %}

## Step 5: Query payment attempts

You can check the status of payments made through a link by querying the link itself:

```bash
curl -X GET "https://api.plexo.com.uy/v1/payment-links/a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -u "YOUR_USERNAME:YOUR_PASSWORD"
```

For one-time links, the status changes to `completed` after the first successful payment. For regular links, you can list payment attempts associated with the link using the public endpoint.

## Best practices

### Set expiration dates

Always set `validUntil` for time-sensitive payments (invoices, offers, etc.). This prevents stale links from being used after the payment window has closed.

### Use per-link callbacks

If you handle different payment types differently (e.g. invoices vs donations), use `settings.callbackUrl` to route notifications to specific endpoints rather than relying on the global merchant setting.

### Choose the right type

* Use `regular` for ongoing payment collection (subscriptions, recurring invoices).
* Use `one-time` for single transactions (individual invoices, one-off purchases).
* Use `quick-pay` for on-the-fly payments that don't need a pre-created link.

### Configure installments per payment method

Use the installments map to offer different plans per card brand:

```json
{
  "installments": {
    "VISA": [1, 3, 6, 12],
    "MASTERCARD": [1, 3, 6],
    "*": [1]
  }
}
```

The `"*"` key acts as a wildcard default for payment methods not explicitly listed.

### Use displayName and description

Always provide a clear `displayName` and `description` — they are shown to the payer on the checkout page and help reduce payment abandonment.

## Next steps

* [Split Payments](/rest-api/payment-links/split-payments.md) — Distribute payments across multiple merchants.
* [Payment Links API Reference](/rest-api/api-reference/payment-links.md) — Full endpoint documentation.
* [Callbacks Guide](/rest-api/operations/callbacks.md) — Detailed callback payload and verification.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://plexo.gitbook.io/rest-api/payment-links/integration-guide.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.