Create a Payment Link

POST

payment-link

curl -X POST https://api.therius.io/v1/payment-link \
  -H "Authorization: Bearer prv_production_your_key_here" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantCode": "MERCHANT_001",
    "type": "one-time",
    "amount": { "currency": "BRL", "value": 15000, "exponent": 2 },
    "title": "Invoice 4821",
    "reference": "INV-4821",
    "customerEmail": "ana@example.com",
    "returnUrl": "https://shop.example.com/thanks",
    "expiresInDays": 14
  }'

{
  "id": "5b1f0a52-3c0e-4a52-9d57-0c1d7e9f2a10",
  "url": "https://pay.therius.io/pay/Zk3x...",
  "type": "one-time",
  "status": "active",
  "amountMode": "fixed",
  "amount": { "currency": "BRL", "value": 15000, "exponent": 2 },
  "title": "Invoice 4821",
  "reference": "INV-4821",
  "customerEmail": "ana@example.com",
  "returnUrl": "https://shop.example.com/thanks",
  "saveCardEnabled": false,
  "reusable": false,
  "usesCount": 0,
  "environment": "production",
  "expiresAt": "2026-10-28T12:00:00Z",
  "createdAt": "2026-10-14T12:00:00Z"
}

POST /payment-link creates a hosted checkout page you can send to a payer by email, chat, or QR code — no SDK integration needed. The response contains the url to share.

Link types

One-time, fixed amount — you set amount (amountMode: "fixed", the default). Use it for invoices and tickets.
One-time, payer-entered amount — set amountMode: "customer_entered" and a currency. The payer types the amount, optionally bounded by amountMin and amountMax (minor units).
Subscription — set type: "subscription" and a subscriptionPlanId. The plan sets the price. Omit subscriptionPlanId and the payer picks from your active plans. Don’t send amount on subscription links.

Single-use and reusable links

By default a link is single-use: it moves to used after the first successful payment. Failed attempts don’t consume it, so the payer can retry. Set reusable: true to accept many payments. Add maxUses to cap the number of successful payments; the link becomes used when the cap is reached. Without maxUses, a reusable link stays active until it expires or you cancel it. maxUses requires reusable: true, and subscription links can’t be reusable.

Environment and expiry

A link takes the environment of the key that created it: prv_sandbox_ keys create sandbox links, prv_production_ keys create production links. Links expire after 7 days unless you set expiresInDays (1–365) or expiresAt (YYYY-MM-DD, end of that day in UTC).

Reference and return URL

reference is your own identifier (an invoice number, for example). It becomes the orderCode of the resulting payment. returnUrl must be an https URL (http is accepted in sandbox).

Example

curl -X POST https://api.therius.io/v1/payment-link \
  -H "Authorization: Bearer prv_production_your_key_here" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantCode": "MERCHANT_001",
    "type": "one-time",
    "amount": { "currency": "BRL", "value": 15000, "exponent": 2 },
    "title": "Invoice 4821",
    "reference": "INV-4821",
    "customerEmail": "ana@example.com",
    "returnUrl": "https://shop.example.com/thanks",
    "expiresInDays": 14
  }'

{
  "id": "5b1f0a52-3c0e-4a52-9d57-0c1d7e9f2a10",
  "url": "https://pay.therius.io/pay/Zk3x...",
  "type": "one-time",
  "status": "active",
  "amountMode": "fixed",
  "amount": { "currency": "BRL", "value": 15000, "exponent": 2 },
  "title": "Invoice 4821",
  "reference": "INV-4821",
  "customerEmail": "ana@example.com",
  "returnUrl": "https://shop.example.com/thanks",
  "saveCardEnabled": false,
  "reusable": false,
  "usesCount": 0,
  "environment": "production",
  "expiresAt": "2026-10-28T12:00:00Z",
  "createdAt": "2026-10-14T12:00:00Z"
}

Send an Idempotency-Key header so a retried request returns the original link instead of creating a second one. See Idempotency.

Authorizations

Authorization

string

header

required

Your secret API key: Bearer prv_production_xxx (production) or Bearer prv_sandbox_xxx (sandbox).

Headers

Idempotency-Key

string<uuid>

A UUID you generate per operation. Required in production. Retrying with the same key returns the original response.

Body

application/json

type

enum<string>

required

Available options:

one-time,

subscription

merchantCode

string

Your merchant account identifier. Required if the key maps to more than one merchant account.

amountMode

enum<string>

default:fixed

One-time links only.

Available options:

fixed,

customer_entered

amount

object

Required for one-time links. value is required when amountMode is fixed; for customer_entered only currency is needed. Not allowed on subscription links.

Show child attributes

amountMin

integer<int64>

customer_entered only. Minimum amount the payer may enter, minor units.

amountMax

integer<int64>

customer_entered only. Maximum amount the payer may enter, minor units.

subscriptionPlanId

integer<int64>

Subscription links only. Omit to let the payer choose among your active plans.

checkoutConfigId

string<uuid>

Checkout Builder configuration to style the page.

title

string

Maximum string length: 255

description

string

Maximum string length: 2000

reference

string

Your own reference (invoice number, PNR). It becomes the orderCode of the resulting payment.

Maximum string length: 128

customerEmail

string

customerName

string

returnUrl

string<uri>

Where to send the payer after paying. Must be https (sandbox also allows http).

expiresInDays

integer

default:7

Required range: 1 <= x <= 365

expiresAt

string

Expiry date, YYYY-MM-DD (end of that day, UTC). Takes precedence over expiresInDays.

saveCardEnabled

boolean

default:false

reusable

boolean

default:false

Accept many payments instead of one. One-time links only.

maxUses

integer

Cap on successful payments for a reusable link. Requires reusable: true.

Required range: x >= 1

Response

Payment link created

string<uuid>

url

string<uri>

The hosted checkout URL to share with the payer.

type

enum<string>

Available options:

one-time,

subscription

status

enum<string>

used once a single-use link takes its first successful payment, or a reusable link reaches maxUses.

Available options:

active,

used,

expired,

cancelled

amountMode

enum<string>

Available options:

fixed,

customer_entered

amount

object

Absent on subscription links. For customer_entered links only currency and exponent are set.

Show child attributes

amountMin

integer<int64>

Minimum payer-entered amount, minor units.

amountMax

integer<int64>

Maximum payer-entered amount, minor units.

subscriptionPlanId

integer<int64>

checkoutConfigId

string<uuid>

title

string

description

string

reference

string

customerEmail

string

customerName

string

returnUrl

string<uri>

saveCardEnabled

boolean

reusable

boolean

maxUses

integer

usesCount

integer

Number of successful payments taken through this link.

environment

enum<string>

Available options:

production,

sandbox

expiresAt

string<date-time>

usedAt

string<date-time>

createdAt

string<date-time>

curl -X POST https://api.therius.io/v1/payment-link \
  -H "Authorization: Bearer prv_production_your_key_here" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantCode": "MERCHANT_001",
    "type": "one-time",
    "amount": { "currency": "BRL", "value": 15000, "exponent": 2 },
    "title": "Invoice 4821",
    "reference": "INV-4821",
    "customerEmail": "ana@example.com",
    "returnUrl": "https://shop.example.com/thanks",
    "expiresInDays": 14
  }'

{
  "id": "5b1f0a52-3c0e-4a52-9d57-0c1d7e9f2a10",
  "url": "https://pay.therius.io/pay/Zk3x...",
  "type": "one-time",
  "status": "active",
  "amountMode": "fixed",
  "amount": { "currency": "BRL", "value": 15000, "exponent": 2 },
  "title": "Invoice 4821",
  "reference": "INV-4821",
  "customerEmail": "ana@example.com",
  "returnUrl": "https://shop.example.com/thanks",
  "saveCardEnabled": false,
  "reusable": false,
  "usesCount": 0,
  "environment": "production",
  "expiresAt": "2026-10-28T12:00:00Z",
  "createdAt": "2026-10-14T12:00:00Z"
}

Payments

Payment Links

Tokenization

Subscriptions

Subscription Plans

SDK Session

Create a Payment Link

Link types

Single-use and reusable links

Environment and expiry

Reference and return URL

Example

Authorizations

Headers

Body

Response

​Link types

​Single-use and reusable links

​Environment and expiry

​Reference and return URL

​Example

Authorizations

Headers

Body

Response

Link types

Single-use and reusable links

Environment and expiry

Reference and return URL

Example