Criar Transferência Pix

Este endpoint realiza um pagamento para uma chave Pix. Para fazê-lo deve ser efetuada a chamada para a API, como especificado abaixo:

Request

A chamada deverá ser feita utilizando o método POST.

URL

{BaseUrl}/api/v1/pix/transfers

HTTP Headers - Exemplo:

Authorization: Basic {base64(client_id:client_secret)}
Content-Type: application/json

HTTP Request Body

{
        "value": 250.00,
        "pix_key": "email@exemplo.com",
        "pix_key_type": "email",
        "recipient_name": "Maria Santos",
        "recipient_tax_id": "12345678901",
        "client_ref": "PAG-67890"
}

Descrição dos Atributos

ATRIBUTO	DESCRIÇÃO	TIPO
value (Obrigatório)	Valor da transferência em reais	DECIMAL maior que 0
pix_key (Obrigatório)	Chave PIX do destinatário	STRING limite de 100 caracteres
pix_key_type (Obrigatório)	Tipo da chave PIX	ENUM cpf (11 dígitos numéricos - 12345678901) cnpj (14 dígitos numéricos - 12345678000190) phone (+55 + DDD + número - +5511999998888) email (e-mail válido - pagamentos@empresa.com) evp (UUID (chave aleatória) -a1b2c3d4-e5f6-7890-abcd-1234567890ab)
recipient_name (Opcional)	Nome do destinatário	STRING limite de 100 caracteres
recipient_tax_id (Opcional)	CPF/CNPJ do destinatário	STRING limite de 14 caracteres Apenas números
client_ref (Opcional)	Referência externa única para identificação	STRING limite de 100 caracteres

informação

Idempotência: o client_ref é único por empresa. Se uma requisição for reenviada com um client_ref já utilizado, nenhuma nova transferência será criada — a API retornará HTTP 200 com os dados da transferência original. Recomendamos sempre informá-lo para permitir reenvios seguros em caso de timeout.

Exemplo cURL - bash

curl -X POST https://api.moneyguard.com.br/api/v1/pix/transfers \
    -H "Authorization: Bearer seu_access_token" \
  -H "Content-Type: application/json" \
  -d '{
    "value": 250.00,
    "pix_key": "12345678901",
    "pix_key_type": "cpf",
    "recipient_name": "Maria Santos",
    "recipient_tax_id": "12345678901",
    "client_ref": "PAG-67890"
}'

Response

Após a chamada, é retornado um JSON com o status 201 - Created caso o procedimento tenha ocorrido com sucesso.

HTTP 201 Response Body

{
        "transfer_id": "550e8400-e29b-41d4-a716-446655440000",
        "client_ref": "PAG-67890"
}

Descrição dos Atributos

ATRIBUTO	DESCRIÇÃO	TIPO
transfer_id (Obrigatório)	Código de referência único da transferência	STRING limite de 100 caracteres
client_ref (Opcional)	Referência externa informada na criação (null quando não informada)	STRING limite de 255 caracteres

Error

Em caso de erros, será retornado um json com o atributo error especificando o motivo de a operação ter sido rejeitada.

HTTP 400 Response Body - Erro de validação

{
    "error": "Could not create transfer: {detalhes da validação}"
}

HTTP 404 Response Body - PIX-out não habilitado

{
    "error": "Not found"
}

aviso

O envio de transferências (PIX-out) precisa estar habilitado para as suas credenciais. Caso contrário, o endpoint retorna HTTP 404. Entre em contato com a equipe Moneyguard para habilitá-lo.