Generate PIX Charge (Cash-In)

POST /api/pix/cash-in

POST https://api.fypay.me/api/pix/cash-in

Requires a Bearer token in the Authorization header. See Generate Token to obtain one.

Generates a dynamic QR Code for receiving payments via PIX. The charge is created with status PENDING and, when paid, the status changes to CONFIRMED via webhook.

Authentication

Requires a Bearer token in the Authorization header.

Request Body

Field	Type	Required	Description
`transaction`	object	Yes	Transaction data
`transaction.value`	number	Yes	Amount in BRL (up to 2 decimal places). Minimum: `0.01`
`transaction.description`	string	Yes	Transaction description (max 100 characters)
`transaction.externalId`	string	Yes	External transaction ID (unique per account, max 50 characters; must not start with `MIRROR:`)
`transaction.expirationTime`	number	No	Expiration time in seconds (min 30s, max 7 days). Default: `86400` (24h). Some providers require higher minimums — see Per-provider limits
`transaction.generateQrCode`	boolean	No	If `true`, returns the QR Code in Base64. Default: `false`
`payer`	object	Yes	Payer data (informational — not sent to the PSP)
`payer.fullName`	string	Yes	Payer's name. Informational — a fixed value may be used (e.g., the account's legal name). Max: 100 chars
`payer.document`	string	Yes	CPF (11 digits) or CNPJ (14 digits), digits only. Informational — you may use the integrator's own CNPJ
`additionalInfo`	object	No	Additional information (string:string key-value pairs, maximum 10 keys; the `mirror` key is reserved)
`splits`	array	No	List of split payment recipients (maximum 10). When the PIX-IN is confirmed, the amount is automatically divided. The sum of splits plus fees cannot exceed the transaction amount
`splits[].pixKey`	string	Yes	PIX key of the split recipient (max 255 chars)
`splits[].pixKeyType`	string	Yes	Key type: `EMAIL`, `PHONE`, `CPF`, `CNPJ`, `RANDOM`
`splits[].name`	string	Yes	Recipient name (max 255 chars)
`splits[].document`	string	Yes	CPF (11 digits) or CNPJ (14 digits), numbers only
`splits[].type`	string	Yes	Split type: `FIXED` (fixed amount in BRL) or `PERCENTAGE` (percentage over gross amount)
`splits[].value`	number	Yes	Split value. `FIXED`: BRL amount with up to 2 decimals (e.g., `10.50`). `PERCENTAGE`: percentage directly (e.g., `10` = 10%). Minimum: `0.01`
`splits[].immediate`	boolean	No	If `true`, the split is executed immediately after the PIX-IN. Default: `false` (follows the account's configured frequency)

Request Examples

Minimal scenario: generates a charge without QR Code and without additional data.

{
  "transaction": {
    "value": 49.90,
    "description": "Assinatura mensal - Plano Básico",
    "externalId": "SUB-2024-001"
  },
  "payer": {
    "fullName": "Maria Silva",
    "document": "12345678909"
  }
}

Most common scenario: generates a QR Code to display to the payer, with order metadata and 1-hour expiration.

{
  "transaction": {
    "value": 189.90,
    "description": "Pedido #8842 - Loja Virtual",
    "externalId": "ORD-8842-20240115",
    "expirationTime": 3600,
    "generateQrCode": true
  },
  "payer": {
    "fullName": "Carlos Oliveira",
    "document": "98765432000198"
  },
  "additionalInfo": {
    "orderId": "8842",
    "storeName": "Tech Solutions",
    "customerEmail": "carlos@email.com"
  }
}

High-value charge (B2B) with long expiration (7 days) and CNPJ as payer.

{
  "transaction": {
    "value": 15750.00,
    "description": "NF 2024/0042 - Consultoria em TI",
    "externalId": "NF-2024-0042",
    "expirationTime": 604800,
    "generateQrCode": true
  },
  "payer": {
    "fullName": "Empresa ABC Ltda",
    "document": "11222333000181"
  },
  "additionalInfo": {
    "nfNumber": "2024/0042",
    "contractId": "CTR-789"
  }
}

Marketplace: a R$ 200 payment split between the seller (70%), platform (20%), and courier (R$ 10 fixed). Splits will be executed according to the frequency configured on the account.

{
  "transaction": {
    "value": 200.00,
    "description": "Pedido #12345 - Marketplace",
    "externalId": "MKT-12345",
    "generateQrCode": true
  },
  "payer": {
    "fullName": "João Pereira",
    "document": "12345678909"
  },
  "splits": [
    {
      "pixKey": "vendedor@email.com",
      "pixKeyType": "EMAIL",
      "name": "Loja do João",
      "document": "98765432000198",
      "type": "PERCENTAGE",
      "value": 70
    },
    {
      "pixKey": "11222333000181",
      "pixKeyType": "CNPJ",
      "name": "Marketplace Ltda",
      "document": "11222333000181",
      "type": "PERCENTAGE",
      "value": 20
    },
    {
      "pixKey": "11999887766",
      "pixKeyType": "PHONE",
      "name": "Entregador Silva",
      "document": "98765432100",
      "type": "FIXED",
      "value": 10.00
    }
  ]
}

Result after payment confirmation:

Recipient	Type	Calculation	Amount
Loja do João	70%	R$ 200 x 70%	R$ 140.00
Marketplace Ltda	20%	R$ 200 x 20%	R$ 40.00
Entregador Silva	Fixed	—	R$ 10.00
Remaining balance	—	R$ 200 - R$ 190	R$ 10.00

Single split with immediate execution: as soon as the payment is confirmed, the transfer to the provider is made automatically (without waiting for the account's frequency).

{
  "transaction": {
    "value": 350.00,
    "description": "Serviço de consultoria - Projeto Alpha",
    "externalId": "SVC-ALPHA-001",
    "generateQrCode": true
  },
  "payer": {
    "fullName": "Empresa XYZ S.A.",
    "document": "55666777000181"
  },
  "splits": [
    {
      "pixKey": "a1b2c3d4-e5f6-4890-abcd-ef1234567890",
      "pixKeyType": "RANDOM",
      "name": "Consultor Freelancer",
      "document": "12345678909",
      "type": "PERCENTAGE",
      "value": 80,
      "immediate": true
    }
  ]
}

See the Payment Split guide for full details on types, calculations, frequencies, and advanced examples.

Code Examples

cURL

curl -X POST "https://api.fypay.me/api/pix/cash-in" \
  -H "Authorization: Bearer $FYPAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "transaction": {
    "value": 49.90,
    "description": "Assinatura mensal - Plano Básico",
    "externalId": "SUB-2024-001"
  },
  "payer": {
    "fullName": "Maria Silva",
    "document": "12345678909"
  }
}'

const axios = require('axios');

const response = await axios.post('https://api.fypay.me/api/pix/cash-in',
  {
  "transaction": {
    "value": 49.90,
    "description": "Assinatura mensal - Plano Básico",
    "externalId": "SUB-2024-001"
  },
  "payer": {
    "fullName": "Maria Silva",
    "document": "12345678909"
  }
},
  {
    headers: {
      'Authorization': `Bearer ${process.env.FYPAY_TOKEN}`,
      'Content-Type': 'application/json',
    },
  }
);
console.log(response.data);

import os, requests

response = requests.post(
    'https://api.fypay.me/api/pix/cash-in',
    headers={
        'Authorization': f'Bearer {os.environ["FYPAY_TOKEN"]}',
        'Content-Type': 'application/json',
    },
    json={
  "transaction": {
    "value": 49.90,
    "description": "Assinatura mensal - Plano Básico",
    "externalId": "SUB-2024-001"
  },
  "payer": {
    "fullName": "Maria Silva",
    "document": "12345678909"
  }
},
)
print(response.json())

$ch = curl_init('https://api.fypay.me/api/pix/cash-in');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('FYPAY_TOKEN'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => '{
  "transaction": {
    "value": 49.90,
    "description": "Assinatura mensal - Plano Básico",
    "externalId": "SUB-2024-001"
  },
  "payer": {
    "fullName": "Maria Silva",
    "document": "12345678909"
  }
}',
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

String body = """
    {
      "transaction": {
        "value": 49.90,
        "description": "Assinatura mensal - Plano Básico",
        "externalId": "SUB-2024-001"
      },
      "payer": {
        "fullName": "Maria Silva",
        "document": "12345678909"
      }
    }
    """;
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.fypay.me/api/pix/cash-in"))
    .header("Authorization", "Bearer " + System.getenv("FYPAY_TOKEN"))
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(body))
    .build();
HttpResponse<String> response = HttpClient.newHttpClient()
    .send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Response (201 Created)

Field	Type	Description
`transactionId`	string	Unique identifier of the generated transaction
`correlationId`	string	Transaction correlation ID (UUID)
`externalId`	string	External transaction ID (same value as input)
`status`	string	Transaction status: `PENDING` (awaiting payment)
`pixCode`	string	PIX code in standard EMV format (copy and paste)
`generateTime`	string	PIX generation date and time (ISO 8601)
`expirationDate`	string	PIX expiration date and time (ISO 8601)
`qrCodeImage`	string	QR Code in Base64 (only when `generateQrCode=true`)

{
  "transactionId": "7845",
  "correlationId": "550e8400-e29b-41d4-a716-446655440000",
  "externalId": "ORD-8842-20240115",
  "status": "PENDING",
  "pixCode": "00020126580014br.gov.bcb.pix0136550e8400-e29b-41d4-a716-4466554400005204000053039865802BR5916Tech Solutions Ltda6009SAO PAULO62070503***63041D3D",
  "generateTime": "2024-01-15T10:30:00.000Z",
  "expirationDate": "2024-01-15T11:30:00.000Z",
  "qrCodeImage": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAASwAAAEsCAYAAAB5fY51..."
}

Returned when the body does not pass validation. Errors in nested fields (transaction.*, payer.*, splits[]) come with message as a list, one message per field. Errors in top-level fields (for example, missing transaction or an unknown field) come with code: PUB_REQUEST_BODY_INVALID and the fields in details.violations.

{
  "statusCode": 400,
  "timestamp": "2026-04-10T15:27:36.608Z",
  "path": "/api/pix/cash-in",
  "method": "POST",
  "code": "HTTP_ERROR",
  "message": [
    "transaction.value deve ser no mínimo 0.01",
    "transaction.description deve ter no máximo 100 caracteres"
  ],
  "userMessage": "Requisição inválida. Verifique os dados enviados.",
  "errorId": "31b5dc36b86c598e51a2a5389a37060d",
  "error": "Bad Request"
}

Common causes:

transaction.value less than 0.01 or with more than 2 decimal places
transaction.description or transaction.externalId empty, description longer than 100 characters or externalId longer than 50
externalId already used on this account (PIX_DUPLICATE_EXTERNAL_ID)
expirationTime less than 30 (seconds) or greater than 604800 (7 days)
expirationTime less than the account provider minimum (errorCode PROVIDER_EXPIRATION_BELOW_MINIMUM) — see Per-provider limits
Sum of splits exceeds the transaction amount

Token missing, expired, or invalid.

{
  "statusCode": 401,
  "timestamp": "2026-04-10T15:30:00.000Z",
  "path": "/api/pix/cash-in",
  "method": "POST",
  "code": "HTTP_ERROR",
  "message": "Token Bearer não fornecido",
  "userMessage": "Acesso não autorizado. Faça login novamente.",
  "errorId": "a9f3e2b1c4d5678e90123456abcdef01",
  "error": "Unauthorized"
}

Failed to communicate with the PIX provider. Try again.

{
  "statusCode": 500,
  "timestamp": "2026-04-10T15:30:00.000Z",
  "path": "/api/pix/cash-in",
  "method": "POST",
  "code": "HTTP_ERROR",
  "message": "Internal Server Error",
  "userMessage": "Ocorreu um erro interno. Tente novamente mais tarde.",
  "errorId": "c7d8e9f0a1b2345678901234abcdef56",
  "error": "Internal Server Error"
}