Skip to main content
POST
/
api
/
v2
/
gateway
/
request-qrcode
Gera um QR Code PIX para recebimento de pagamento
curl --request POST \
  --url https://sandbox.ws.relaxpay.site/api/v2/gateway/request-qrcode \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "requestNumber": "PEDIDO-12345",
  "dueDate": "2024-12-31T00:00:00.000Z",
  "amount": 100,
  "shippingAmount": 10,
  "usernameCheckout": "usuario123",
  "callbackUrl": "https://seu-site.com/webhook/relaxpay",
  "client": {
    "name": "João Silva",
    "taxId": "123.456.789-00",
    "email": "[email protected]"
  },
  "split": {
    "username": "parceiro123",
    "percentageSplit": 10
  }
}
'
{
  "idTransaction": "0b935d10-3c90-4af3-8776-dd18622a7941",
  "paymentCode": "00020101021226890014br.gov.bcb.pix...",
  "paymentCodeBase64": "iVBORw0KGgoAAAANSUhEUgAAAPoAAAD6AQ...",
  "response": "OK",
  "expiresAt": "2024-12-31T23:59:59.000Z"
}
Gere QR Codes PIX dinâmicos para receber pagamentos de forma rápida e segura.

​
Visão Geral

O endpoint PIX Cash-in permite que você gere QR Codes dinâmicos para recebimento de pagamentos PIX. Este é o método ideal para integrar pagamentos PIX em e-commerces, marketplaces e outros sistemas que necessitam receber pagamentos instantâneos.

​
Endpoint

​
Parâmetros da Requisição

​
requestNumber
string
required
Identificador único do pedido em seu sistema
​
dueDate
string
required
Data de vencimento do QR Code (formato AAAA-MM-DD)
​
amount
number
required
Valor do pagamento em reais
​
shippingAmount
number
Valor do frete (opcional)
​
usernameCheckout
string
Usuário do checkout (para identificação)
​
callbackUrl
string
required
URL para notificações de pagamento
​
client
object
Dados do cliente que irá efetuar o pagamento
​
split
object
Configuração para divisão de pagamento (split)

​
Exemplos de Requisição

​
Resposta de Sucesso

​
200 - OK
object
{
  "idTransaction": "0b935d10-3c90-4af3-8776-dd18622a7941",
  "paymentCode": "00020101021226890014br.gov.bcb.pix2567brcode-h.sandbox.starkinfra.com/v2/2b625b826e2f40d29e0b71fbc78904795204000053039865802BR5918Suit Business Ltda6007Goiania62070503***6304F01C",
  "paymentCodeBase64": "iVBORw0KGgoAAAANSUhEUgAAAPoAAAD6AQAAAACgl2eQAAACvElEQVR4Xu2YS...",
  "response": "OK",
  "expiresAt": "2024-12-31T23:59:59Z"
}

​
Usando o QR Code

1

Exibir o QR Code para o usuário

Utilize o campo paymentCodeBase64 para exibir a imagem do QR Code:
<img src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAPoAAAD6AQAAAACgl2eQAAACvElEQVR4Xu2YS..." alt="QR Code PIX" />
2

Disponibilizar o código copia-e-cola

Ofereça o campo paymentCode como alternativa ao QR Code:
<button onclick="copyToClipboard('00020101021226890014br.gov.bcb.pix...')">
  Copiar código PIX
</button>
3

Verificar o status do pagamento

Consulte o status do pagamento utilizando o endpoint consult-transaction ou espere a notificação via webhook.

​
Códigos de Erro

Os parâmetros fornecidos são inválidos ou estão em formato incorreto.
{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "INVALID_AMOUNT",
  "details": "O valor informado é inválido"
}
As credenciais fornecidas são inválidas ou não foram enviadas.
{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "INVALID_CREDENTIALS",
  "details": "As credenciais fornecidas são inválidas"
}

​
Notificações (Webhooks)

Você receberá notificações na URL de callback informada quando o status do pagamento for alterado: 
{
  "event": "pix.received",
  "data": {
    "idTransaction": "0b935d10-3c90-4af3-8776-dd18622a7941",
    "status": "PAID",
    "amount": 100.00,
    "paidAt": "2024-12-15T14:30:45Z"
  }
}

​
Boas Práticas

Utilize sempre um identificador único no campo requestNumber para evitar duplicidade de cobranças.
Para melhorar a experiência do usuário, exiba tanto o QR Code quanto o código copia-e-cola.
  • Armazene o idTransaction em seu sistema para posterior consulta e reconciliação
  • Defina a data de vencimento (dueDate) adequada ao seu modelo de negócio
  • Implemente a verificação de status para atualizar seu sistema quando o pagamento for confirmado
  • Em casos de split, certifique-se de que o username do parceiro está correto e ativo

​
Exemplo de Implementação

Authorizations

​
Authorization
string
header
required

Token de autenticação Bearer usando o Client Secret para a versão v2 da API

Body

application/json
​
requestNumber
string
required

Identificador único do pedido

Example:

"PEDIDO-12345"

​
dueDate
string<date>
required

Data de vencimento do QR Code

Example:

"2024-12-31T00:00:00.000Z"

​
amount
number
required

Valor do pagamento

Example:

100

​
callbackUrl
string<uri>
required

URL para notificações

Example:

"https://seu-site.com/webhook/relaxpay"

​
shippingAmount
number

Valor do frete

Example:

10

​
usernameCheckout
string

Usuário do checkout

Example:

"usuario123"

​
client
object
​
split
object

Response

QR Code gerado com sucesso

​
idTransaction
string<uuid>

ID da transação PIX

Example:

"0b935d10-3c90-4af3-8776-dd18622a7941"

​
paymentCode
string

Código PIX em formato copia e cola

Example:

"00020101021226890014br.gov.bcb.pix..."

​
paymentCodeBase64
string

QR Code em formato Base64

Example:

"iVBORw0KGgoAAAANSUhEUgAAAPoAAAD6AQ..."

​
response
string

Status da resposta

Example:

"OK"

​
expiresAt
string<date-time>

Data e hora de expiração do QR Code

Example:

"2024-12-31T23:59:59.000Z"