---
title: "Creates a link to a payment form where guests can pay."
method: POST
path: "/finance/v1/folios/{folioId}/payments/by-link"
tags: ["FolioPayments"]
---

# Creates a link to a payment form where guests can pay.

`POST /finance/v1/folios/{folioId}/payments/by-link`

## Request

- Base URL: `https://api.apaleo.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.apaleo.com/finance/v1/folios/{folioId}/payments/by-link`
- Auth: OAuth 2
  - Implicit: `https://identity.apaleo.com/connect/authorize`
  - Scopes: `folios.manage`, `admin`

Creates a link to a payment form where guests can pay. To enable open invoice payment methods you need to provide at
least the paid charges with the request. For some open invoice payment methods you also need to ensure that the full
billing address of the folio is set, before you create the payment link. The payment will be processed asynchronously.
Use the location header to poll for the status of the payment. As long as a payment is pending it reduces the amount
of allowed payments for the folio.<br>You must have this scope: 'folios.manage'.<br>For fine-grained clients, you must have this permission: 'core.folio_payments.create'.

## Path parameters

- `folioId` string, required

## Headers

- `Idempotency-Key` string

## Request body

- CreatePaymentLinkRequest
  - `expiresAt` string, date-time, required: The date that the link expires<br />A date and time (without fractional second part) in UTC or with UTC offset as defined in <a href="https://en.wikipedia.org/wiki/ISO_8601">ISO8601:2004</a>
  - `countryCode` string, required: The payer's country code. Used to provide suitable for the payer payment methods and use default country language
  - `description` string, nullable: Payment description. It will be shown on the payment form of the link
  - `payerEmail` string, email, nullable: The email address of the payer or cardholder. It can be used to verify the identity of the payer and allow to catch a fraudulent usage of the payment account if the email address does not match the one on file at the bank
  - `returnUrl` string, nullable: Website URL used for redirection after payment is completed using the payment link.
  - `amount` MonetaryValueModel, required
    - `amount` number, double, required
    - `currency` string, required
  - `paidCharges` PaymentPaidChargesRequest[], nullable: List of charges and amount being covered by this payment.
    - `chargeId` string, required: The ID of the charge being paid
    - `amount` number, double, required: The amount being covered with the payment. If not provided it is assumed that the payment is covering the full amount of the charge

## Response `201`

Payment was created and will be processed.

- PaymentCreatedModel
  - `id` string, required

## Other responses

- `400`: Bad request.
- `401`: You are unauthorized.
- `403`: Forbidden.
- `404`: The Request-URI could not be found.
- `415`: Unsupported media type.
- `422`: Validation errors in the request body or query params.
- `499`: Client closed request.
- `500`: An unexpected error occurred.
- `503`: The server is currently unavailable. Please try later.

---

[API](https://skmtc.dev/apaleo/apis/apaleo-finance-api.md) - [All operations](https://skmtc.dev/apaleo/apis/apaleo-finance-api/llms.txt) - [OpenAPI document](https://skmtc.dev/apaleo/apis/apaleo-finance-api/revisions/6f1d524c1ea7?raw)