payba3

payba3 Agent Integration Guide

This file is the agent-facing contract for using @grtsnx/payba3 inside IDE assistants, AI coding agents, workflow builders, and tool servers.

Discovery Order

When an agent needs to integrate payba3:

1. Read @grtsnx/payba3/llms.txt.
2. Read @grtsnx/payba3/agents.md.
3. Read @grtsnx/payba3/llms-full.txt when broader context is needed.
4. Read every provider-specific file needed for the requested channel:
   • @grtsnx/payba3/llms/paystack.txt
   • @grtsnx/payba3/llms/safehaven.txt
   • @grtsnx/payba3/llms/seerbit.txt
   • @grtsnx/payba3/llms/opay.txt
   • @grtsnx/payba3/llms/mono.txt
   • @grtsnx/payba3/llms/monnify.txt
   • @grtsnx/payba3/llms/qoreid.txt

Core Contract

• Package: @grtsnx/payba3
• Runtime: server-side JavaScript or TypeScript
• Main import: createPayba3
• Provider selector: payba3.use('<provider>')
• Error surface: Payba3Error
• Supported providers: paystack, safehaven, seerbit, opay, mono, monnify, qoreid

import { createPayba3 } from '@grtsnx/payba3';

const payba3 = createPayba3({
  paystack: {
    secretKey: process.env.PAYSTACK_SECRET_KEY,
  },
});

const paystack = payba3.use('paystack');

IDE Agent Instructions

When generating code:

• Install @grtsnx/payba3 if it is missing.
• Generate server-side code only.
• Ask the developer for the provider they want to use.
• Ask only for the credentials required by that provider.
• Prefer environment variables or the host app's secret manager.
• Use explicit createPayba3({ provider: { ...config } }) configuration when it improves clarity.
• Keep provider-specific request validation in the host app or tool wrapper.
• Never place provider secrets in frontend code, generated examples, comments, tests, logs, or fixtures.

Tool Wrapper Pattern

Agents should expose narrow tools that match business actions, not raw provider clients.

import { createPayba3 } from '@grtsnx/payba3';

const payba3 = createPayba3({
  paystack: {
    secretKey: process.env.PAYSTACK_SECRET_KEY,
  },
});

type InitializeCheckoutInput = {
  email: string;
  amountInKobo: number;
  reference: string;
};

export async function initializePaystackCheckout(
  input: InitializeCheckoutInput,
) {
  return payba3.use('paystack').initializeOneTimeCheckout({
    email: input.email,
    amountInKobo: input.amountInKobo,
    currency: 'NGN',
    reference: input.reference,
  });
}