Node.js SDK

npm install @yativo/fiat-sdk

# or
pnpm add @yativo/fiat-sdk
yarn add @yativo/fiat-sdk

const yativo = new Yativo({
  apiKey: process.env.YATIVO_API_KEY,
  apiSecret: process.env.YATIVO_API_SECRET,
  environment: 'sandbox', // or 'production'
});

node --env-file=.env first-request.mjs

const endpoint = await yativo.webhookEndpoints.create({ url: 'https://your-shop.com/webhooks/yativo' });
console.log(endpoint.secret); // copy this into YATIVO_WEBHOOK_SECRET. Don't share it.

import express from 'express';
import Yativo, { WebhookHandler } from '@yativo/fiat-sdk';

const yativo = new Yativo();
const app = express();

const webhooks = new WebhookHandler(process.env.YATIVO_WEBHOOK_SECRET)
  .on('deposit.updated', async (event) => {
    // Ask Yativo directly instead of trusting the message.
    const deposit = await yativo.deposits.retrieve(event.payload.id);
    if (deposit.status === 'success') {
      // mark the order paid
    }
  })
  .on('payout.updated', async (event) => {
    console.log('Payout', event.payload.id, 'is now', event.payload.status);
  });

// IMPORTANT: use express.raw here, not express.json. The signature is checked on the raw body.
app.post('/webhooks/yativo', express.raw({ type: 'application/json' }), webhooks.express());

app.listen(3000);

// Next.js App Router (app/api/webhooks/yativo/route.ts), Cloudflare Workers, Bun, Deno, Hono:
export const POST = webhooks.fetch();

// Plain Node.js http server:
http.createServer(webhooks.node()).listen(3000);

const order = await yativo.cardCheckout.createOrder(
  {
    customer_id: 'your-selling-customer-id', // must have an approved card_checkout endorsement
    amount: '49.99',                          // a string with 2 decimals
    currency: 'USD',
    description: 'Pro plan, 1 month',
    reference: 'INV-10023',                   // your invoice number (must be unique)
    customer_email: 'buyer@example.com',
    success_url: 'https://your-shop.com/thanks',
    cancel_url: 'https://your-shop.com/cart',
  },
  { idempotencyKey: 'INV-10023' },
);

// Send the buyer to order.checkout_url exactly as it is (it's signed).

// 1. Which details does this payout method need? (account number, bank, ...)
const form = await yativo.paymentMethods.payoutForm(methodId);

// 2. Save the person you're paying
const beneficiary = await yativo.beneficiaries.create({
  gateway_id: methodId,
  currency: 'BRL',
  nickname: 'Supplier Ltda',
  payment_data: { /* the fields from the form */ },
});

// 3. Lock a rate
const quote = await yativo.rates.quote({
  from_currency: 'USD', to_currency: 'BRL', amount: 500,
  method_id: methodId, method_type: 'payout',
});

// 4. Send it
const payout = await yativo.payouts.create(
  { debit_wallet: 'USD', payment_method_id: beneficiary.id, quote_id: quote.quote_id },
  { idempotencyKey: 'invoice-778' },
);

const response = await yativo.request('GET', '/some/new/endpoint', { query: { page: 1 } });

import { ValidationError, YativoError } from '@yativo/fiat-sdk';

try {
  await yativo.deposits.create({ gateway: 22, currency: 'USD' }); // amount is missing
} catch (err) {
  if (err instanceof ValidationError) {
    console.log('Please fix:', err.fields); // { amount: ['The amount field is required.'] }
  } else if (err instanceof YativoError) {
    console.log(err.status, err.code, err.message); // e.g. 403 forbidden "This IP address is not allowed..."
  } else {
    throw err;
  }
}

// One page
const page = await yativo.deposits.list({ currency: 'BRL', per_page: 50 });
console.log(page.data, page.pagination);

// Every page, one item at a time
for await (const deposit of yativo.paginate((q) => yativo.deposits.list(q), { per_page: 100 })) {
  console.log(deposit.id, deposit.status);
}

const yativo = new Yativo({ environment: 'sandbox' });
await yativo.sandbox.simulateWebhook('payin'); // sends deposit.created and deposit.updated to your URL