POST
/
api
/
v2
/
gateway
/
pix-payment
curl --request POST \
  --url https://sandbox.ws.relaxpay.site/api/v2/gateway/pix-payment \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --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/v2/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:

​
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

​
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.

Authorizations

​
Authorization
string
header
required

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

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

200
application/json
Transferência iniciada com sucesso
​
idTransaction
string

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"