Setup a New Program

This guide walks a Tenant through creating and configuring a new card Program — from initial creation in Account Management through to having program-level credentials ready for use. It's the starting point for every integration: no Cardholder can be created, no Card issued, and no Wallet used until a Program is live and credentialed.

❗️

This guide describes operations performed via Account Management, which is available exclusively to Tenants with production API keys. The steps below cannot be performed in the staging environment. Full Account Management operational documentation is provided separately to production Tenants. If you are a new Tenant and do not yet have Account Management access, contact your Axys account team to begin your onboarding.

Prerequisites

Before setting up a new Program, ensure you have:

• Completed initial Tenant onboarding (manual, with Axys) — including your Tenant-level mTLS certificate, IP allowlist entry, and Tenant-level API key
• The legal/brand details for this Program (trading name, which will appear as OU in the Program's certificate and may appear on cards)
• A decision on the Program's base currency (USD, CAD, GBP, or EUR — cannot be changed after creation)
• An initial transaction-limit ceiling for the Program
• Whether 3-D Secure will be enabled for this Program
• Card artwork for at least design slot 0 (the mandatory default design), sized and prepared to card-network brand standards (Visa or Mastercard, as applicable)
• Your Program's calling IP address(es) from which the program-level API will be called
• DNS/PTR record access to configure forward-confirmed reverse DNS for those IPs

Step 1: Create the Program

Via Account Management, create the Program record, specifying at minimum:

🚧

Base currency is permanent. Once a Program is created, its base currency cannot be changed — all Cards, Wallets, balances, and limits in the Program are denominated in this currency. If you need a different currency for a different market or product, create a separate Program. Think carefully about multi-currency needs before confirming this setting.

Step 2: Generate a CSR and obtain the Program certificate

The Program needs its own mTLS client certificate, separate from the Tenant certificate. Follow the same process as the Tenant onboarding certificate, but scoped to this Program:

# Generate a new RSA-2048 key pair for this Program
openssl genrsa -out program-a.key 2048

Create a CSR configuration, ensuring:

• O = your Tenant's legal entity name (same as the Tenant certificate)
• OU = this Program's trading/brand name
• CN / SAN = every domain and IP from which the program-level API will be called (no wildcards)

openssl req -new -key program-a.key -out program-a.csr -config program-a-openssl.cnf

Submit the CSR (PEM-formatted) via Account Management. The signed certificate is returned, typically within 24 hours. Download and store it alongside program-a.key in your secrets manager.

For the full certificate generation reference, see mTLS Certificates & CSR.

Step 3: Register the certificate expiry webhook

Register the HTTPS callback URL to which Axys will deliver certificate expiry reminders at 30, 15, and 5 days before the Program certificate expires:

Account Management → Program → Certificates → Webhook URL

See Webhooks & Callback Notifications for how to handle these callbacks.

Step 4: Allowlist the Program's calling IP(s)

Register the IP address(es) from which your integration will call the program-level API. Also configure:

• A records on each of the domains in the certificate's CN/SAN, pointing to the calling IP(s)
• PTR records (reverse DNS) on the calling IP(s), resolving back to those domains

Both A records and PTR records are required for the FCrDNS check to pass. See IP Allowlisting & Network Security.

Step 5: Submit the default Card Design (slot 0)

A Program cannot issue physical cards until design slot 0 is approved. Submit the artwork for the default design via Account Management. The review process typically takes several business days.

While awaiting card design approval, the Program can still:

• Onboard Cardholders
• Issue virtual cards (virtual cards are not affected by card design status)
• Fund cards and wallets

See Card Programs & Designs for design requirements and the approval lifecycle.

Step 6: Verify the Program is ready

Before directing live traffic to the Program, confirm:

• Program-level mTLS certificate is installed alongside the private key
• X-API-Key for the Program is stored in your secrets manager
• Calling IP(s) are allowlisted and DNS/PTR records are in place and propagated
• Certificate expiry webhook is registered and your endpoint is returning 2xx
• Card Design slot 0 is approved (required before physical card issuance)
• Make a test GET /cardholders call — a 200 with an empty items array confirms everything is correctly configured

curl --cert program-a.crt \
     --key program-a.key \
     -H "X-API-Key: YOUR_PROGRAM_API_KEY" \
     "https://production.api.axyscards.com/v2/cardholders"
# Expected: {"status":"success","items":[],"total":0,"limit":50,"offset":0}

Optional: Configure additional deposit address types

If your Program needs to support digital-asset deposits beyond the default EVM/BTC/SOL set (e.g. TRON, AVAX, Cosmos), request additional deposit address types via Account Management before issuing cards — deposit addresses are generated at issuance and the set cannot be changed retroactively for already-issued cards.

See Funding & Deposits.

What's next

With the Program live, the typical next steps are:

• Onboard a New Cardholder
• Issue a Virtual Card
• Issue & Activate a Physical Card