Take your first payment

This guide walks through the basic flow with a test key: register a business, add a customer, and charge them. The example is a café, but the steps are the same for a salon, a gym, a shop, or a school.

The examples use the Node SDK, @payofy/node. The API reference shows the same calls in cURL and JavaScript.

import { Payofy } from "@payofy/node";

const payofy = new Payofy({ apiKey: process.env.PAYOFY_SECRET_KEY });

1. Register the business (merchant)

A merchant is a business that takes payments through your app.

const merchant = await payofy.merchants.create({
  schoolName: "Blue Door Café",
  contactEmail: "owner@bluedoorcafe.example",
});

note

The business name field is currently called schoolName. It will be renamed to a general name before general availability.

2. Add a customer

A customer is the person who pays the business.

const customer = await payofy.customers.create({
  merchantId: merchant.id,
  name: "Jane Smith",
  email: "jane@example.com",
});

3. Charge the customer

Amounts are in cents: 1250 is $12.50.

const payment = await payofy.payments.createIntent({
  merchantId: merchant.id,
  customerId: customer.id,
  amountCents: 1250,
  currency: "USD",
  paymentMethodToken: "tok_test_4242",
  idempotencyKey: "order-1042",
});

console.log(payment.status); // e.g. "succeeded"

Why idempotencyKey matters

Networks fail. If your request times out, you don't know whether the charge went through. Always send the same idempotencyKey when you retry the same purchase, so Payofy can recognise the retry instead of treating it as a new charge. Use something unique to the purchase, such as your order ID.

4. Check the payment later

const latest = await payofy.payments.get(payment.id);

Handling errors

Errors come back with an HTTP status and a JSON body:

{ "statusCode": 401, "error": "UNAUTHORIZED", "message": "Missing or malformed Authorization header" }

Status	Meaning
400	Something in the request is missing or invalid
401	The API key is missing or invalid
500	Something went wrong on Payofy's side. Retry with the same idempotencyKey.

Preview

Payofy is in active development, and some endpoints still return sample data. Use test keys only.