Inicio Rápido

Requisitos Previos

Antes de comenzar, necesita tener:

✓Certificado de cliente X.509 (PEM, RSA 2048, válido por 2 años) vinculado a su cuenta, con su clave privada

✓Credenciales OAuth (clientId y clientSecret)

Genere sus credenciales en el Dashboard de FyPay, en Configuración → Credenciales. El clientSecret se muestra una sola vez: cópielo en el momento.

1. Configurar el Entorno

Cree un archivo .env con sus credenciales:

FYPAY_CLIENT_ID=6967c0a0-3566-48d0-8c13-717038b52279
FYPAY_CLIENT_SECRET=su-client-secret
FYPAY_API_URL=https://api.fypay.me/api

Guarde el certificado como client.crt y la clave privada como client.key en el directorio del proyecto. El certificado solo se usa para generar el token, presentado en el handshake TLS (mTLS).

2. Instalar Dependencias

npm install axios dotenv

pip install requests python-dotenv

3. Código Completo

El siguiente ejemplo se autentica, consulta el saldo y crea un cobro PIX:

require('dotenv').config();
const axios = require('axios');
const fs = require('fs');
const https = require('https');

const API_URL = process.env.FYPAY_API_URL;

const mtlsAgent = new https.Agent({
  cert: fs.readFileSync('./client.crt'),
  key: fs.readFileSync('./client.key')
});

// 1. Get token (mTLS: certificate in the TLS handshake)
async function getToken() {
  const response = await axios.post(`${API_URL}/auth/token`, {
    clientId: process.env.FYPAY_CLIENT_ID,
    clientSecret: process.env.FYPAY_CLIENT_SECRET
  }, {
    httpsAgent: mtlsAgent,
    headers: { 'Content-Type': 'application/json' }
  });
  return response.data.access_token;
}

// 2. Check balance
async function getBalance(token) {
  const response = await axios.get(`${API_URL}/balance`, {
    headers: { 'Authorization': `Bearer ${token}` }
  });
  return response.data;
}

// 3. Create PIX charge
async function createPixCharge(token, value, description, externalId, payer) {
  const response = await axios.post(`${API_URL}/pix/cash-in`, {
    transaction: {
      value,
      description,
      externalId,
      expirationTime: 3600, // 1 hour
      generateQrCode: true
    },
    payer: {
      fullName: payer.name,
      document: payer.document
    }
  }, {
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json'
    }
  });
  return response.data;
}

// Run
async function main() {
  try {
    // Authenticate
    console.log('Authenticating...');
    const token = await getToken();
    console.log('Token obtained successfully!');

    // Check balance
    console.log('\nChecking balance...');
    const balance = await getBalance(token);
    console.log(`Available balance: R$ ${balance.netBalance.toFixed(2)}`);

    // Create charge
    console.log('\nCreating PIX charge...');
    const charge = await createPixCharge(token, 100.00, 'Integration test', 'ORDER-001', {
      name: 'John Smith',
      document: '12345678909'
    });

    console.log(`\nCharge created!`);
    console.log(`ID: ${charge.transactionId}`);
    console.log(`Status: ${charge.status}`);
    console.log(`PIX Copy and Paste: ${charge.pixCode}`);
    console.log(`Expires at: ${charge.expirationDate}`);

  } catch (error) {
    console.error('Error:', error.response?.data || error.message);
  }
}

main();

import os
import requests
from dotenv import load_dotenv

load_dotenv()

API_URL = os.getenv('FYPAY_API_URL')

# 1. Get token (mTLS: certificate in the TLS handshake)
def get_token():
    response = requests.post(f'{API_URL}/auth/token',
        json={
            'clientId': os.getenv('FYPAY_CLIENT_ID'),
            'clientSecret': os.getenv('FYPAY_CLIENT_SECRET')
        },
        cert=('client.crt', 'client.key')
    )
    response.raise_for_status()
    return response.json()['access_token']

# 2. Check balance
def get_balance(token):
    response = requests.get(f'{API_URL}/balance',
        headers={'Authorization': f'Bearer {token}'}
    )
    response.raise_for_status()
    return response.json()

# 3. Create PIX charge
def create_pix_charge(token, value, description, external_id, payer_name, payer_document):
    response = requests.post(f'{API_URL}/pix/cash-in',
        json={
            'transaction': {
                'value': value,
                'description': description,
                'externalId': external_id,
                'expirationTime': 3600,
                'generateQrCode': True
            },
            'payer': {
                'fullName': payer_name,
                'document': payer_document
            }
        },
        headers={
            'Authorization': f'Bearer {token}',
            'Content-Type': 'application/json'
        }
    )
    response.raise_for_status()
    return response.json()

# Run
def main():
    try:
        # Authenticate
        print('Authenticating...')
        token = get_token()
        print('Token obtained successfully!')

        # Check balance
        print('\nChecking balance...')
        balance = get_balance(token)
        print(f"Available balance: R$ {balance['netBalance']:.2f}")

        # Create charge
        print('\nCreating PIX charge...')
        charge = create_pix_charge(
            token,
            100.00,
            'Integration test',
            'ORDER-001',
            'John Smith',
            '12345678909'
        )

        print(f"\nCharge created!")
        print(f"ID: {charge['transactionId']}")
        print(f"Status: {charge['status']}")
        print(f"PIX Copy and Paste: {charge['pixCode']}")
        print(f"Expires at: {charge['expirationDate']}")

    except requests.exceptions.RequestException as e:
        print(f'Error: {e.response.json() if e.response else e}')

if __name__ == '__main__':
    main()

4. Ejecutar

node quickstart.js

python quickstart.py

Salida esperada:

Authenticating...
Token obtained successfully!

Checking balance...
Available balance: R$ 48734.90

Creating PIX charge...

Charge created!
ID: 7845
Status: PENDING
PIX Copy and Paste: 00020126580014br.gov.bcb.pix...
Expires at: 2024-01-20T14:30:00.000Z

5. Recibir Notificaciones (Webhook)

Configure un endpoint para recibir notificaciones cuando se confirma un pago:

// Express.js
app.post('/webhook/fypay', (req, res) => {
  const { event, transactionId, status, finalAmount } = req.body;

  if (event === 'CashIn' && status === 'CONFIRMED') {
    console.log(`Payment ${transactionId} confirmed: R$ ${finalAmount}`);
    // Update order in your system
  }

  res.status(200).send('OK');
});