快速入门

前提条件

在开始之前，您需要具备以下条件：

✓已关联到您账户的 X.509 证书（.pem 文件）

✓OAuth 凭证（clientId 和 clientSecret）

通过 Avista 控制面板申请您的凭证和证书。

1. 配置环境

使用您的凭证创建 .env 文件：

NTXPAY_CLIENT_ID=account-93-your-id
NTXPAY_CLIENT_SECRET=your-secret-password
NTXPAY_API_URL=https://api.ntxpay.com

将您的证书保存为项目目录中的 client-cert.pem。

2. 安装依赖

npm install axios dotenv

pip install requests python-dotenv

3. 完整代码

以下示例演示认证、查询余额和创建 PIX 收款：

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

const API_URL = process.env.NTXPAY_API_URL;
const certificate = fs.readFileSync('./client-cert.pem', 'utf8');
const encodedCert = encodeURIComponent(certificate);

// 1. Get token
async function getToken() {
  const response = await axios.post(`${API_URL}/api/auth/token`, {
    clientId: process.env.NTXPAY_CLIENT_ID,
    clientSecret: process.env.NTXPAY_CLIENT_SECRET
  }, {
    headers: {
      'Content-Type': 'application/json',
      'X-SSL-Client-Cert': encodedCert
    }
  });
  return response.data.access_token;
}

// 2. Check balance
async function getBalance(token) {
  const response = await axios.get(`${API_URL}/api/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}/api/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: '12345678901'
    });

    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 urllib.parse
import requests
from dotenv import load_dotenv

load_dotenv()

API_URL = os.getenv('NTXPAY_API_URL')

# Load certificate
with open('client-cert.pem', 'r') as f:
    certificate = f.read()
    encoded_cert = urllib.parse.quote(certificate)

# 1. Get token
def get_token():
    response = requests.post(f'{API_URL}/api/auth/token',
        json={
            'clientId': os.getenv('NTXPAY_CLIENT_ID'),
            'clientSecret': os.getenv('NTXPAY_CLIENT_SECRET')
        },
        headers={
            'Content-Type': 'application/json',
            'X-SSL-Client-Cert': encoded_cert
        }
    )
    response.raise_for_status()
    return response.json()['access_token']

# 2. Check balance
def get_balance(token):
    response = requests.get(f'{API_URL}/api/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}/api/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',
            '12345678901'
        )

        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. 运行

node quickstart.js

python quickstart.py

预期输出：

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. 接收通知 (Webhook)

设置一个端点，在付款确认时接收通知：

// Express.js
app.post('/webhook/ntxpay', (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');
});