Account and API Key(s) Management Guide
Objective
Authorize and capture
A two-step payment: first authorize the card to reserve funds, then capture to settle them. Use this when you need to confirm funds are available before you commit the charge, such as verifying an order before shipping.
Cancel a subscription
Cancellation ends a subscription's renewals. Payments AI supports two timings:
Collect Payment
Overview
Create customer with payment instrument
This tutorial walks through the three calls that turn a new customer plus a raw card into an attached payment instrument you can charge later.
Create a subscription
This tutorial walks through creating a subscription end-to-end, including the case that surprises most integrators "pending" and the customer must complete the first charge on the hosted payment form.
Custom fields
Custom fields let you attach merchant-defined fields to standard Payments AI resources. A custom field is defined once per Organization and applied to a chosen resource type from this enum: customers, payment-instruments, plans, products, subscriptions, transactions, websites.
Dispute process
This document outlines the structured workflow for managing payment disputes and chargebacks initiated by cardholders through their issuing banks. Please note: This guide is structured specifically for the default Payments AI gateway. Understanding this sequence is crucial for effective defense, recovery, and risk mitigation.
Increase Approval Rate
F.1 — Why Approval Rate Matters
Pause a subscription
Pausing a subscription temporarily stops renewals from running. When the pause is resumed (by deleting it), the subscription returns to active. Confirm the resulting renewal schedule on the subscription after resuming.
Plan CRUD
The Public API exposes operations on the plan entity. A plan is the pricing template applied to a product; it is referenced by planId on subscriptions and one-time orders.
Product CRUD
The Public API exposes CRUD operations on the product entity. A product is what the merchant sells; it is referenced by productId on plans.
Reactivate a subscription
Reactivation reverses a cancellation on a subscription. Whether a given subscription is reactivable depends on its state — confirm via the API response. If the reactivation call returns an error, create a new subscription instead.
Refund a captured transaction
The refund endpoint returns a full or partial amount of funds to a customer. It works for transactions that have already been captured, such as a standard sale or an authorize that you have since captured.
Refund scenarios
A refund returns funds to the customer for a transaction that has already been captured. This page covers common implementation scenarios beyond basic requests: handling multiple partial refunds, processing refunds on active subscriptions, navigating disputes, and managing cases where a customer's card or bank account has changed.
Refund a transaction
Return funds to a customer for a captured transaction. You can refund the full amount or part of it. For information on underlying ledger concepts and balance limitations, see Refunds.
Retrieve the Bank Identification Number (BIN)
For Enterprise clients with advanced fraud-analysis or treasury-routing needs, transaction responses can include the Bank Identification Number (BIN) — the first 6 digits of the card number. This field is opt-in and gated by a feature toggle tied to your account's PCI compliance status.
Tokenization endpoint
The tokenization endpoint converts raw card data into a short-lived token. You attach the token to a customer to create a reusable payment instrument; raw card data never has to be stored on your servers. Payments AI does not retain the raw card data either — only the token is persisted on the platform side.
Dispute webhooks
Introduction
How to set up a webhook
Pre-requisites:
Websites
The Public API exposes endpoints for managing the websites registered under an Organization. A website is identified by a name and a url.