Docs
Abrir o painel

Criar link

POST
/links

Cria um link de pagamento e devolve o id e a url do checkout.

Envie X-Idempotency-Key para que retentativas da mesma requisição não criem links duplicados: a resposta da primeira chamada é devolvida de novo. Se você não enviar, geramos uma chave e a devolvemos no header de mesmo nome.

Autorização

SecretIDSecretKey
headerX-Secret-ID<token>

ID da credencial de API, gerado no painel.

headerX-Secret-Key<token>

Chave secreta da credencial. Nunca exponha no front-end.

Cabeçalhos

X-Idempotency-Key?string

Chave única por operação (ex. um UUID). Repetir a chave devolve a resposta original.

Corpo da requisição

application/json
  1. body
description*string

Descrição exibida no checkout.

amount?string

Valor decimal. Sem amount o link é dinâmico e o pagador informa o valor.

currency?string
Default"BRL"
Value in"BRL""USD"
single_use?boolean

Se true, o link aceita um único pagamento concluído.

Defaultfalse
expiration?integer

Expiração em Unix timestamp UTC (segundos). Vale para links com amount.

Formatint64
external_ref?string

Sua referência (ex. ID do pedido). Volta nos webhooks em data.link.external_ref.

back_url?string

Para onde o pagador volta depois do checkout.

Formaturi
webhook_url?string

Restringe os eventos deste link ao webhook cadastrado com exatamente esse endpoint. Sem ele, todos os webhooks da conta recebem. A URL precisa já estar cadastrada em POST /webhook, senão nenhum evento é entregue.

Formaturi
logo_url?string

Sobrescreve o logo configurado na conta.

Formaturi
fee_mode?FeeMode

Quem paga a taxa do cartão: customer_pays repassa ao pagador, merchant_absorbs desconta do valor recebido.

Default"customer_pays"
Value in"customer_pays""merchant_absorbs"
max_installments?integer

Máximo de parcelas no cartão. 0 usa o padrão da conta (12 se não houver).

Range0 <= value <= 12
metadata?

Dados para pré-preencher o checkout. Todos opcionais.

Corpo da resposta

Link criado.

application/json
  1. response
id?string
Formatuuid
url?string

URL do checkout para enviar ao pagador.

Formaturi
curl -X POST 'https://sandbox.xpayz.us/payment-link/links' \  -H 'Content-Type: application/json' \  -d '{  "description": "Pedido #123",  "amount": "100.00",  "currency": "BRL",  "single_use": true,  "expiration": 1798761599,  "external_ref": "order-123",  "back_url": "https://example.com/obrigado",  "webhook_url": "https://example.com/webhooks/xpayz",  "fee_mode": "customer_pays",  "max_installments": 12,  "metadata": {    "name": "John Doe",    "document": "12345678909",    "email": "john.doe@example.com",    "phone": "+5511999999999",    "street": "Av. Paulista",    "number": "1000",    "complement": "Apto 101",    "neighborhood": "Bela Vista",    "city": "São Paulo",    "state": "SP",    "country": "BR",    "zip_code": "01311000"  }}'
Exemplo de resposta
{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "url": "http://example.com"}