Criar um link de pagamento

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 cria uma página de checkout hospedada que você pode enviar ao pagador por e-mail, chat ou QR code, sem integrar o SDK. A resposta contém a url para compartilhar.

Tipos de link

Pagamento único, valor fixo — você define amount (amountMode: "fixed", o padrão). Use para faturas e passagens.
Pagamento único, valor informado pelo pagador — defina amountMode: "customer_entered" e uma currency. O pagador digita o valor, opcionalmente limitado por amountMin e amountMax (unidades menores).
Assinatura — defina type: "subscription" e um subscriptionPlanId. O plano define o preço. Se você omitir subscriptionPlanId, o pagador escolhe entre seus planos ativos. Não envie amount em links de assinatura.

Links de uso único e reutilizáveis

Por padrão um link é de uso único: ele passa para used após o primeiro pagamento bem-sucedido. Tentativas que falham não o consomem, então o pagador pode tentar de novo. Defina reusable: true para aceitar vários pagamentos. Adicione maxUses para limitar a quantidade de pagamentos bem-sucedidos; o link passa para used ao atingir o limite. Sem maxUses, um link reutilizável permanece active até expirar ou até você cancelá-lo. maxUses exige reusable: true, e links de assinatura não podem ser reutilizáveis.

Ambiente e validade

Um link assume o ambiente da chave que o criou: chaves prv_sandbox_ criam links de sandbox e chaves prv_production_ criam links de produção. Os links expiram em 7 dias, a menos que você defina expiresInDays (1–365) ou expiresAt (YYYY-MM-DD, fim desse dia em UTC).

Referência e URL de retorno

reference é o seu próprio identificador (por exemplo, o número de uma fatura). Ele vira o orderCode do pagamento resultante. returnUrl deve ser uma URL https (em sandbox http é aceito).

Exemplo

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"
}

Envie um cabeçalho Idempotency-Key para que uma requisição repetida retorne o link original em vez de criar um segundo. Veja Idempotência.

Autorizações

Authorization

string

header

obrigatório

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

Cabeçalhos

Idempotency-Key

string<uuid>

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

Corpo

application/json

type

enum<string>

obrigatório

Opções disponíveis:

one-time,

subscription

merchantCode

string

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

amountMode

enum<string>

padrão:fixed

One-time links only.

Opções disponíveis:

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

padrão:7

Intervalo necessário: 1 <= x <= 365

expiresAt

string

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

saveCardEnabled

boolean

padrão:false

reusable

boolean

padrão:false

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

maxUses

integer

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

Intervalo necessário: x >= 1

Resposta

Payment link created

string<uuid>

url

string<uri>

The hosted checkout URL to share with the payer.

type

enum<string>

Opções disponíveis:

one-time,

subscription

status

enum<string>

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

Opções disponíveis:

active,

used,

expired,

cancelled

amountMode

enum<string>

Opções disponíveis:

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>

Opções disponíveis:

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"
}

Pagamentos

Links de pagamento

Tokenização

Assinaturas

Subscription Plans

Sessão do SDK

Criar um link de pagamento

Tipos de link

Links de uso único e reutilizáveis

Ambiente e validade

Referência e URL de retorno

Exemplo

Autorizações

Cabeçalhos

Corpo

Resposta

​Tipos de link

​Links de uso único e reutilizáveis

​Ambiente e validade

​Referência e URL de retorno

​Exemplo

Autorizações

Cabeçalhos

Corpo

Resposta

Tipos de link

Links de uso único e reutilizáveis

Ambiente e validade

Referência e URL de retorno

Exemplo