Skip to main content
POST
/
api
/
v1
/
gateway
/
pix-payment
Realiza uma transferência PIX
curl --request POST \
  --url https://sandbox.ws.relaxpay.site/api/v1/gateway/pix-payment \
  --header 'Content-Type: application/json' \
  --header 'ci: <ci>' \
  --header 'cs: <cs>' \
  --data '
{
  "value": 150,
  "key": 62999998888,
  "typeKey": "phoneNumber",
  "callbackUrl": "https://seu-site.com/webhook/relaxpay",
  "externalId": "PAGAMENTO-12345",
  "documentValidation": "123.456.789-00"
}
'
{
  "idTransaction": "10dc395c-bee0-4368-a980-85a610987e30",
  "status": "PROCESSING",
  "response": "OK"
}
O PIX Cash-out permite que você realize transferências financeiras instantâneas para qualquer chave PIX, ideal para pagamentos a fornecedores, reembolsos e saques.

​
Visão Geral

O fluxo de PIX Cash-out consiste em:
1

Solicitar transferência

Sua aplicação envia uma requisição de pagamento para a API RelaxPay
2

Processamento do pagamento

O sistema RelaxPay processa e valida a transferência junto ao Banco Central
3

Confirmação da operação

Você recebe uma notificação via webhook quando a transferência é concluída

​
Realizar Transferência PIX

Endpoint

POST /api/v1/gateway/pix-payment

​
Parâmetros

​
key
string
required
Chave PIX do destinatário
​
typeKey
string
required
Tipo da chave PIX
​
value
number
required
Valor da transferência (ex: 156.79)
​
callbackUrl
string
required
URL para receber notificações sobre o pagamento
​
documentValidation
string
CPF/CNPJ para validar se pertence à chave PIX informada (opcional)
​
externalId
string
ID para controle de duplicidade em seu sistema (opcional)

​
Exemplo

​
Notificações

Para informações detalhadas sobre notificações de webhook, consulte a página de Webhooks.
Quando uma transferência for processada, você receberá notificações com a seguinte estrutura:
​
event
string
transfer.completed
{
  "event": "transfer.completed",
  "data": {
    "idTransaction": "10dc395c-bee0-4368-a980-85a610987e30",
    "typeTransaction": "PIX_CASHOUT",
    "statusTransaction": "PAID_OUT",
    "value": 150.00,
    "destinationName": "Maria Oliveira",
    "destinationTaxId": "123.456.789-00",
    "destinationBank": "Banco XYZ"
  }
}
​
event
string
transfer.failed
{
  "event": "transfer.failed",
  "data": {
    "idTransaction": "10dc395c-bee0-4368-a980-85a610987e30",
    "typeTransaction": "PIX_CASHOUT",
    "statusTransaction": "ERROR",
    "value": 150.00,
    "errorCode": "PIX_KEY_NOT_FOUND",
    "errorMessage": "A chave PIX informada não foi encontrada"
  }
}

​
Códigos de Status

PAID_OUT

Transferência concluída com sucesso

ERROR

Erro no processamento da transferência

CANCELED

Transferência cancelada

RETURNED

Valor devolvido pelo destinatário

​
Segurança

Por motivos de segurança, somente IPs cadastrados podem realizar operações de PIX Cash-out.

​
Configuração de IP

1

Acesse seu Dashboard

Entre no Dashboard RelaxPay e faça login
2

Navegue até Gerenciamento de IPs

Acesse GATEWAY/CHECKOUT > GERENCIAMENTO DE IPs
3

Adicione seu IP

Inclua o endereço IP do seu servidor que fará as requisições
Tela de gerenciamento de IPs

​
Boas Práticas

Use externalId: Sempre inclua um identificador único para evitar pagamentos duplicados
Valide documentos: Quando possível, use documentValidation para maior segurança
Processamento assíncrono: Trate as transferências de forma assíncrona via webhooks
Mecanismo de retry: Implemente retentativas em caso de falhas temporárias

​
Códigos de Erro

Para uma lista completa dos códigos de erro e suas soluções, consulte a página de Erros.
​
NO_FUNDS
error
Saldo insuficiente para realizar a transferência
​
PIX_KEY_NOT_FOUND
error
A chave PIX informada não foi encontrada
​
DOCUMENT_VALIDATE
error
A chave PIX não pertence ao documento informado
​
DUPLICATE_EXTERNAL_ID
warning
O externalId já foi utilizado em outra transação
​
UNAUTHORIZED_IP
error
O IP que está tentando realizar a operação não está autorizado

Headers

​
ci
string
required

Client ID para autenticação

​
cs
string
required

Client Secret para autenticação

Body

application/json
​
value
number
required

Valor da transferência

Example:

150

​
key
string
required

Chave PIX de destino

Example:

62999998888

​
typeKey
enum<string>
required

Tipo da chave PIX

Available options:
document,
phoneNumber,
email,
randomKey,
paymentCode
Example:

"phoneNumber"

​
callbackUrl
string<uri>
required

URL para notificações

Example:

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

​
externalId
string

Identificador externo

Example:

"PAGAMENTO-12345"

​
documentValidation
string

CPF/CNPJ para validação

Example:

"123.456.789-00"

Response

Transferência iniciada com sucesso

​
idTransaction
string<uuid>

ID da transação PIX

Example:

"10dc395c-bee0-4368-a980-85a610987e30"

​
status
enum<string>

Status da transferência

Available options:
PROCESSING,
COMPLETED,
FAILED
Example:

"PROCESSING"

​
response
string

Status da resposta

Example:

"OK"