API Documentation

Base URL: https://jopay.me/api/checkout/v1

Authentication

Include your API key in the Authorization header as a Bearer token.

Find your API keys in Admin → Settings → Checkout API Keys. Use test keys for development and live keys for production.

Header
Authorization: Bearer sk_live_your_api_key
POST

/sessions

Create Checkout Session

Create a new checkout session and redirect your customer to the returned URL. After payment, they'll be redirected to your success_url.

Parameters

amount_cents required integer

Amount in cents. 2500 = €25.00

currency required string

Three-letter ISO code: eur, usd, gbp

success_url required string

Redirect URL after payment. We append ?session_id={id}

cancel_url required string

Redirect URL if customer cancels

customer_email string

Email for invoice delivery

metadata object

Key-value pairs returned in webhooks

billing_details object

Name, address, tax_id for invoices

curl -X POST https://jopay.me/api/checkout/v1/sessions \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "amount_cents": 2500,
    "currency": "eur",
    "customer_email": "customer@example.com",
    "success_url": "https://yoursite.com/success",
    "cancel_url": "https://yoursite.com/cancel",
    "metadata": {"order_id": "12345"}
  }'

Response

{
  "id": "cs_a1b2c3d4e5f6...",
  "url": "https://jopay.me/checkout/cs_a1b2c3d4e5f6",
  "status": "open",
  "amount_cents": 2500,
  "currency": "eur",
  "customer_email": "customer@example.com",
  "expires_at": "2025-01-10T13:00:00Z"
}
GET

/sessions/:id

Retrieve Session

Retrieve an existing session to check payment status. Use this to verify payment completion on your success page.

Status Values

open

Session is active and awaiting payment

completed

Payment was successful

expired

Session expired without payment (1 hour timeout)

curl https://jopay.me/api/checkout/v1/sessions/cs_a1b2c3d4e5f6 \
  -H "Authorization: Bearer sk_live_your_api_key"

Webhooks

Configure your webhook endpoint in Admin → Settings → Checkout Webhook. We send events when payment status changes.

Events

checkout.session.completed

Payment successful. Fulfill the order.

checkout.session.expired

Session expired without payment.

Payload

{
  "event": "checkout.session.completed",
  "data": {
    "id": "cs_a1b2c3d4e5f6...",
    "status": "completed",
    "amount_cents": 2500,
    "currency": "eur",
    "customer_email": "customer@example.com",
    "metadata": {"order_id": "12345"},
    "completed_at": "2025-01-10T12:05:00Z"
  },
  "timestamp": "2025-01-10T12:05:01Z"
}

Verifying Signatures

Verify the X-JoPay-Signature header to ensure the webhook is authentic. Compare the HMAC-SHA256 signature using your webhook secret.

# Verify signature using openssl
SIGNATURE="sha256=abc123..."
PAYLOAD='{"event":"checkout.session.completed",...}'
SECRET="whsec_your_webhook_secret"

EXPECTED=$(echo -n "$PAYLOAD" | openssl dgst -sha256 -hmac "$SECRET")
echo "sha256=$EXPECTED"

# Compare with received signature

Billing Details

Include billing details for B2B customers who need invoices with their company name and VAT number.

Tax ID Types

eu_vat

EU VAT Number

gb_vat

UK VAT Number

us_ein

US EIN

au_abn

AU ABN

Example
{
  "billing_details": {
    "name": "Acme Corporation",
    "address": {
      "line1": "123 Business Street",
      "city": "Lisbon",
      "postal_code": "1000-001",
      "country": "PT"
    },
    "tax_id": {
      "type": "eu_vat",
      "value": "PT123456789"
    }
  }
}

Errors

The API returns standard HTTP status codes with JSON error details.

Status Codes

200 Request succeeded
400 Invalid parameters
401 Invalid or missing API key
404 Resource not found
500 Server error

Error Response

{
  "error": {
    "code": "invalid_parameter",
    "message": "amount_cents must be greater than 0",
    "param": "amount_cents"
  }
}

Need Help?

Contact us if you have questions about the API.