Quick Start

Follow this guide to create a customer, generate an invoice, and check its status using the SafePays API V2.

Get Your API Key

Log in to your SafePays Dashboard
Navigate to Settings → API Keys
Click Generate New API Key
Copy and securely store your API key

Your API key is shown only once. Store it securely and never expose it in client-side code.

Create Your First Customer

Create a customer profile to associate with invoices:

curl -X POST https://app.safepays.com/api/v2/customer \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "your_api_key_here",
    "name": "John Doe",
    "email": "john.doe@example.com",
    "preferred_currency": "USD"
  }'

const response = await fetch('https://app.safepays.com/api/v2/customer', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    api_key: 'your_api_key_here',
    name: 'John Doe',
    email: 'john.doe@example.com',
    preferred_currency: 'USD'
  })
});

const customer = await response.json();
console.log('Customer ID:', customer.customer.id);

import requests
import json

url = 'https://app.safepays.com/api/v2/customer'
headers = {'Content-Type': 'application/json'}
data = {
    'api_key': 'your_api_key_here',
    'name': 'John Doe',
    'email': 'john.doe@example.com',
    'preferred_currency': 'USD'
}

response = requests.post(url, headers=headers, data=json.dumps(data))
customer = response.json()
print(f"Customer ID: {customer['customer']['id']}")

Save the customer.id from the response — you'll need it for the next step.

Create Your First Invoice

Now create an invoice for the customer. Optionally provide a redirect_url and webhook_url to handle post-payment flow:

curl -X POST https://app.safepays.com/api/v2/invoice \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "your_api_key_here",
    "customer_id": "550e8400-e29b-41d4-a716-446655440000",
    "currency": "USD",
    "items": [
      { "title": "Product A", "qty": 2, "price": 50.00 }
    ],
    "redirect_url": "https://yoursite.com/thank-you",
    "webhook_url": "https://yoursite.com/webhooks/safepays"
  }'

const response = await fetch('https://app.safepays.com/api/v2/invoice', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    api_key: 'your_api_key_here',
    customer_id: '550e8400-e29b-41d4-a716-446655440000',
    currency: 'USD',
    items: [
      { title: 'Product A', qty: 2, price: 50.00 }
    ],
    redirect_url: 'https://yoursite.com/thank-you',
    webhook_url: 'https://yoursite.com/webhooks/safepays'
  })
});

const invoice = await response.json();
console.log('Payment Link:', invoice.invoice.payment_link);

import requests
import json

url = 'https://app.safepays.com/api/v2/invoice'
headers = {'Content-Type': 'application/json'}
data = {
    'api_key': 'your_api_key_here',
    'customer_id': '550e8400-e29b-41d4-a716-446655440000',
    'currency': 'USD',
    'items': [
        {'title': 'Product A', 'qty': 2, 'price': 50.00}
    ],
    'redirect_url': 'https://yoursite.com/thank-you',
    'webhook_url': 'https://yoursite.com/webhooks/safepays'
}

response = requests.post(url, headers=headers, data=json.dumps(data))
invoice = response.json()
print(f"Payment Link: {invoice['invoice']['payment_link']}")

The webhook_url is optional but recommended — it receives a POST with full transaction details when payment is confirmed. The redirect_url controls where the customer lands after paying.

Check Invoice Status

You can check the status of your invoice at any time:

curl -X GET "https://app.safepays.com/api/v2/invoice/660e8400-e29b-41d4-a716-446655440001?api_key=your_api_key_here"

const invoiceId = '660e8400-e29b-41d4-a716-446655440001';
const apiKey = 'your_api_key_here';

const response = await fetch(
  `https://app.safepays.com/api/v2/invoice/${invoiceId}?api_key=${apiKey}`
);
const result = await response.json();
console.log('Invoice Status:', result.invoice.status);

import requests

invoice_id = '660e8400-e29b-41d4-a716-446655440001'
api_key = 'your_api_key_here'
url = f'https://app.safepays.com/api/v2/invoice/{invoice_id}?api_key={api_key}'

response = requests.get(url)
invoice = response.json()
print(f"Invoice Status: {invoice['invoice']['status']}")

Get Customer Details

Retrieve a customer's profile along with all their paid invoices:

curl -X GET "https://app.safepays.com/api/v2/customer/550e8400-e29b-41d4-a716-446655440000?api_key=your_api_key_here"

const customerId = '550e8400-e29b-41d4-a716-446655440000';
const apiKey = 'your_api_key_here';

const response = await fetch(
  `https://app.safepays.com/api/v2/customer/${customerId}?api_key=${apiKey}`
);
const result = await response.json();
console.log('Customer:', result.customer.name);
console.log('Total Paid:', result.total_paid_count, 'invoices');

import requests

customer_id = '550e8400-e29b-41d4-a716-446655440000'
api_key = 'your_api_key_here'
url = f'https://app.safepays.com/api/v2/customer/{customer_id}?api_key={api_key}'

response = requests.get(url)
result = response.json()
print(f"Customer: {result['customer']['name']}")
print(f"Total Paid: {result['total_paid_count']} invoices")

Next Steps

You've successfully completed the full API workflow:

Created a customer
Generated an invoice with a payment link
Checked the invoice status
Retrieved customer details with payment history

Explore more:

Authentication — API key security best practices
Customers — Full customer endpoint reference
Invoices — Full invoice endpoint reference
Webhooks — Handle real-time payment notifications
Error Handling — Handle errors gracefully