> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.solvimon.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.solvimon.com/_mcp/server.

# Custom redirect

A `CUSTOM_REDIRECT` payment acceptor lets you send customers to a URL of your choosing to complete payment, instead of using a bank account or a payment gateway.

---

## Why this matters

Use a `CUSTOM_REDIRECT` payment acceptor when payment is handled by a system outside Solvimon – for example, a custom checkout page, a payment link generated by another provider, or an internal billing portal.

## How it works

When an invoice is generated, Solvimon builds a payment action for each active payment acceptor attached to it. For a `CUSTOM_REDIRECT` acceptor, the payment action contains a `url` built from the `custom_redirect.url` template configured on the payment acceptor, with any placeholders substituted for the specific invoice and customer.

## Setting it up

### Via API

Create a payment acceptor with [POST /v1/payment-acceptors](https://docs.solvimon.com/api-docs/configuration-api/payment-acceptors/post-payment-acceptors), setting `type` to `CUSTOM_REDIRECT` and a `custom_redirect` object containing the redirect `url`:

**`Create a custom redirect payment acceptor`**

```bash Create a custom redirect payment acceptor
curl -X POST https://test.api.solvimon.com/v1/payment-acceptors \
  -H "X-API-KEY: <apiKey>" \
  -H "Content-Type: application/json" \
  -d '{
    "billing_entity_id": "bien_example",
    "reference": "custom-checkout",
    "type": "CUSTOM_REDIRECT",
    "custom_redirect": {
      "url": "https://pay.example.com/checkout?invoice={{invoice.id}}&customer={{customer.id}}"
    }
  }'
```

**`Response`**

```json Response
{
  "object_type": "PAYMENT_ACCEPTOR",
  "id": "paya_example",
  "billing_entity_id": "bien_example",
  "reference": "custom-checkout",
  "type": "CUSTOM_REDIRECT",
  "status": "ACTIVE",
  "custom_redirect": {
    "url": "https://pay.example.com/checkout?invoice={{invoice.id}}&customer={{customer.id}}"
  }
}
```

Requirements:

* `custom_redirect.url` is required when `type` is `CUSTOM_REDIRECT`, and must be a valid URL.
* The payment acceptor must be owned by a billing entity. Customer-owned payment acceptors only support `BANK_ACCOUNT`.
* Once created, `type` cannot be changed on the payment acceptor, and `custom_redirect` cannot be removed – only its `url` can be updated.

## Supported placeholders

The `url` can include the following placeholders. They're substituted each time an invoice's payment actions are generated, so the resulting link is always specific to that invoice and customer.

| Placeholder              | Replaced with                          |
| ------------------------ | -------------------------------------- |
| `{{invoice.id}}`         | The invoice's resource ID              |
| `{{customer.id}}`        | The customer's resource ID             |
| `{{customer.reference}}` | The customer's reference (URL-encoded) |

For example, the template:

```
https://pay.example.com/checkout?invoice={{invoice.id}}&ref={{customer.reference}}
```

resolves for invoice `invo_example` and customer reference `acme-corp` to:

```
https://pay.example.com/checkout?invoice=invo_example&ref=acme-corp
```

## Outcome on the invoice

The resolved URL is exposed on the invoice under `payment_actions`:

**`Invoice payment action for a custom redirect acceptor`**

```json Invoice payment action for a custom redirect acceptor
{
  "payment_actions": [
    {
      "type": "CUSTOM_REDIRECT",
      "custom_redirect": {
        "url": "https://pay.example.com/checkout?invoice=invo_example&ref=acme-corp"
      }
    }
  ]
}
```

This URL is also used automatically as the payment link in:

* Invoice emails sent to the customer
* Payment confirmation / failure emails
* Upcoming payment reminder emails

> **Note**
>
> No further configuration is needed for these to pick up the custom redirect link – it's resolved the same way the invoice's payment actions are.

### Via Desk

Payment acceptors live on the billing entity. Open the billing entity, go to the payment acceptors section, add an acceptor and pick the custom redirect type, then enter the URL template. The [payment options overview](/platform-guides/platform-configuration/payment-options) shows where the section sits.