Integration Getting Started

This guide helps developers set up their environment and make their first API call to GovPayPlan.

Prerequisites

• GovPayPlan account with API access
• Basic understanding of REST APIs
• Development environment with HTTP client

Step 1: Get API Credentials

Sandbox Credentials

For testing, use sandbox credentials:

1. Log in to the Admin Portal
2. Navigate to Settings > API
3. Find your Sandbox API Key

Production Credentials

Production keys are provided separately after integration review.

WARNING

Never use production credentials for testing. Always use the sandbox environment during development.

Step 2: Understand the API

Base URLs

Environment	Base URL
Sandbox	https://sandbox-api.govpayplan.com/v1
Production	https://api.govpayplan.com/v1

Authentication

All requests require authentication via API key:

Authorization: Bearer YOUR_API_KEY

Request Format

• Content-Type: application/json
• All request bodies should be JSON

Response Format

All responses are JSON:

{
  "success": true,
  "data": { ... },
  "meta": { ... }
}

Step 3: Make Your First Request

Health Check

Verify your setup with a simple health check:

curl -X GET https://sandbox-api.govpayplan.com/v1/health \
  -H "Authorization: Bearer YOUR_API_KEY"

Expected response:

{
  "success": true,
  "data": {
    "status": "healthy",
    "version": "1.0.0"
  }
}

Get Account Info

Retrieve your account information:

curl -X GET https://sandbox-api.govpayplan.com/v1/account \
  -H "Authorization: Bearer YOUR_API_KEY"

Step 4: Create a Test Payment

Payment Request

curl -X POST https://sandbox-api.govpayplan.com/v1/payments \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100.00,
    "currency": "USD",
    "payment_type": "permit_fee",
    "payer": {
      "name": "John Doe",
      "email": "john@example.com"
    },
    "payment_method": {
      "type": "card",
      "card_number": "4242424242424242",
      "exp_month": 12,
      "exp_year": 2025,
      "cvv": "123"
    }
  }'

Response

{
  "success": true,
  "data": {
    "id": "pay_abc123",
    "status": "completed",
    "amount": 100.00,
    "currency": "USD",
    "created_at": "2024-01-15T10:30:00Z"
  }
}

API Resources

Core Endpoints

Endpoint	Method	Description
/payments	POST	Create a payment
/payments/{id}	GET	Get payment details
/payments/{id}/refund	POST	Refund a payment
/transactions	GET	List transactions

Webhooks

Set up webhooks to receive real-time notifications:

• Webhooks Documentation

SDKs and Libraries

Official SDKs

• JavaScript/Node.js
• Python
• PHP
• Ruby

Installation (Node.js example)

npm install @govpayplan/sdk

Usage

const GovPayPlan = require('@govpayplan/sdk');

const client = new GovPayPlan({
  apiKey: 'YOUR_API_KEY',
  sandbox: true
});

const payment = await client.payments.create({
  amount: 100.00,
  currency: 'USD',
  // ...
});

Error Handling

Error Response Format

{
  "success": false,
  "error": {
    "code": "invalid_request",
    "message": "Amount must be greater than 0",
    "details": { ... }
  }
}

Common Error Codes

Code	Description
invalid_request	Request validation failed
authentication_error	Invalid or missing API key
payment_failed	Payment was declined
not_found	Resource not found
rate_limited	Too many requests

Rate Limits

Environment	Limit
Sandbox	100 requests/minute
Production	1000 requests/minute

Next Steps

• Authentication Details
• Webhooks Setup
• Testing Guide