Documentation

Account & Profiles

Account & Profile Management

PerfectPay organizes your setup into a hierarchy: Organization, Merchant Account, and Business Profiles. Each level has its own configuration and API endpoints.

Organizations

An organization is the top-level entity. Most merchants have a single organization.

Retrieve Organization

GET /organization

GET //sandbox.perfectpay.ai/organization
curl https://sandbox.perfectpay.ai/organization \
  -H "api-key: YOUR_SECRET_API_KEY"

Business Profiles

Business profiles let you separate payment configurations within a single merchant account. Each profile can have its own connectors, routing rules, webhook URLs, and branding.

Create a Business Profile

POST /account/{account_id}/business_profile

GET //sandbox.perfectpay.ai/account/merchant_abc123/business_profile
curl https://sandbox.perfectpay.ai/account/merchant_abc123/business_profile \
  -X POST \
  -H "api-key: YOUR_SECRET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "profile_name": "US Online Store",
    "return_url": "https://store.example.com/checkout/complete",
    "webhook_details": {
      "webhook_url": "https://store.example.com/webhooks/perfectpay"
    }
  }'

Retrieve a Business Profile

GET /account/{account_id}/business_profile/{profile_id}

GET //sandbox.perfectpay.ai/account/merchant_abc123/business_profile/pro_abcdefghijklmnop
curl https://sandbox.perfectpay.ai/account/merchant_abc123/business_profile/pro_abcdefghijklmnop \
  -H "api-key: YOUR_SECRET_API_KEY"

Update a Business Profile

PUT /account/{account_id}/business_profile/{profile_id}

GET //sandbox.perfectpay.ai/account/merchant_abc123/business_profile/pro_abcdefghijklmnop
curl https://sandbox.perfectpay.ai/account/merchant_abc123/business_profile/pro_abcdefghijklmnop \
  -X PUT \
  -H "api-key: YOUR_SECRET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "webhook_details": {
      "webhook_url": "https://store.example.com/webhooks/v2"
    }
  }'

Connector Accounts

Connector accounts link a payment processor (Stripe, Adyen, etc.) to your merchant account.

Create a Connector Account

Configure a new processor connection for your merchant. This is typically done via the dashboard, but the API is available for automated setups.

POST /account/{account_id}/connectors

GET //sandbox.perfectpay.ai/account/merchant_abc123/connectors
curl https://sandbox.perfectpay.ai/account/merchant_abc123/connectors \
  -X POST \
  -H "api-key: YOUR_SECRET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "connector_type": "payment_processor",
    "connector_name": "stripe",
    "connector_account_details": {
      "auth_type": "HeaderKey",
      "api_key": "sk_test_..."
    },
    "payment_methods_enabled": [
      {
        "payment_method": "card",
        "payment_method_types": ["credit", "debit"]
      }
    ]
  }'

Retrieve a Connector Account

GET /account/{account_id}/connectors/{merchant_connector_id}

GET //sandbox.perfectpay.ai/account/merchant_abc123/connectors/mca_abc123
curl https://sandbox.perfectpay.ai/account/merchant_abc123/connectors/mca_abc123 \
  -H "api-key: YOUR_SECRET_API_KEY"

Update a Connector Account

PUT /account/{account_id}/connectors/{merchant_connector_id}

Delete a Connector Account

DELETE /account/{account_id}/connectors/{merchant_connector_id}

API Keys

Manage API keys programmatically. Most merchants should use the dashboard instead.

Create an API Key

POST /api_keys/{merchant_id}

GET //sandbox.perfectpay.ai/api_keys/merchant_abc123
curl https://sandbox.perfectpay.ai/api_keys/merchant_abc123 \
  -X POST \
  -H "api-key: YOUR_SECRET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Backend Key",
    "expiration": "2027-01-01T00:00:00Z"
  }'

List API Keys

GET /api_keys/{merchant_id}/list

GET //sandbox.perfectpay.ai/api_keys/merchant_abc123/list
curl https://sandbox.perfectpay.ai/api_keys/merchant_abc123/list \
  -H "api-key: YOUR_SECRET_API_KEY"

Retrieve an API Key

GET /api_keys/{merchant_id}/{key_id}

Update an API Key

PUT /api_keys/{merchant_id}/{key_id}

Delete an API Key

DELETE /api_keys/{merchant_id}/{key_id}

Blocklist

Manage a blocklist of card fingerprints, card BINs, or extended card BINs to automatically decline matching payments.

Add to Blocklist

POST /blocklist

GET //sandbox.perfectpay.ai/blocklist
curl https://sandbox.perfectpay.ai/blocklist \
  -X POST \
  -H "api-key: YOUR_SECRET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "card_bin",
    "data": "411111"
  }'

List Blocklist Entries

GET /blocklist

GET //sandbox.perfectpay.ai/blocklist
curl https://sandbox.perfectpay.ai/blocklist \
  -H "api-key: YOUR_SECRET_API_KEY"

Toggle Blocklist

POST /blocklist/toggle

Enable or disable the blocklist for your merchant account.

Create shareable payment links that open a hosted checkout page.

Payment links are created alongside a payment. Set payment_link to true when creating a payment, and the response includes a payment_link URL.

GET /payment_link/{payment_link_id}

GET //sandbox.perfectpay.ai/payment_link/plink_abc123
curl https://sandbox.perfectpay.ai/payment_link/plink_abc123 \
  -H "api-key: YOUR_SECRET_API_KEY"