Payment API Documentation

Comprehensive, production-ready API for secure payment processing. Built with modern standards, PCI compliance, and developer experience in mind.

Production Ready RESTful API PCI DSS Compliant Real-time Processing
Get Started View Authentication
Quick Example 
curl -X POST https://api.example.com/api/direct-payment \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1000,
    "currency": "USD",
    "payment_method": "card",
    "card_number": "4242424242424242",
    "expiry_month": "12",
    "expiry_year": "2025",
    "cvv": "123"
  }'

Authentication

All API requests require authentication using your API key. Include your API key in the Authorization header of every request.

API Key Authentication 
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.example.com/api/endpoint

Security Best Practices

Important

  • Never expose your API key in client-side code
  • Use HTTPS for all API requests
  • Rotate your API keys regularly
  • Monitor API usage for suspicious activity

Quick Start

Get up and running with our API in just a few steps. This guide will walk you through setting up your first payment integration.

Prerequisites

Before you begin, make sure you have:

  • A merchant account with CircoFlows
  • Basic knowledge of HTTP APIs and JSON
  • A development environment for testing
1

Get Your API Key

Sign up for a merchant account and generate your API key from the dashboard. This key will authenticate all your API requests.

Dashboard Steps:

  1. Log into your merchant dashboard
  2. Navigate to Settings → API Keys
  3. Click Generate New Key
  4. Copy and securely store your API key

Security Note

Never expose your API key in client-side code or public repositories. Use environment variables to store it securely.

2

Make Your First Request

Test your API key with a simple authentication request to ensure everything is working correctly.

Test API Connection 
curl -X GET https://api.example.com/api/health \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Expected Response

You should receive a 200 OK response with API status information.

3

Process Your First Payment

Now let's process a real payment using our test environment. Use the test card numbers provided below.

Test Payment Request 
curl -X POST https://api.example.com/api/direct-payment \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1000,
    "currency": "USD",
    "payment_method": "card",
    "card_number": "4242424242424242",
    "expiry_month": "12",
    "expiry_year": "2025",
    "cvv": "123"
  }'

Test Cards

Success: 4242424242424242
Declined: 4000000000000002
3DS Required: 4000000000003220

Test Environment

Base URL: https://api-test.example.com
Webhook: https://webhook.site/your-url
4

Handle Responses & Webhooks

Process the API response and set up webhooks to receive real-time payment notifications.

Response Handling

Check the response status and handle accordingly:

  • success: true - Payment completed
  • requires_action: true - 3DS needed
  • error - Handle errors gracefully

Webhook Setup

Configure webhooks for real-time updates:

  • Set webhook URL in your dashboard
  • Verify webhook signatures
  • Handle payment status updates
  • Test with webhook.site

What's Next?

Now that you've completed the quick start, explore these resources to build your payment integration:

Direct Payment API

Process payments directly with full control over the flow.

Hosted Payment API

Create secure hosted payment pages with minimal PCI scope.

Webhooks

Set up real-time payment notifications and status updates.

Direct Payment API

Process payments directly through our API with full control over the payment flow. Perfect for custom checkout experiences and server-side payment processing.

Real-time Processing

Instant payment confirmation

Full Control

Customize every aspect of the flow

Secure

End-to-end encryption

3DS Support

Automatic 3D Secure handling

POST /api/direct-payment

Process a payment directly with card details or other payment methods.

Request Parameters

Parameter Type Required Description
amount integer Yes Amount in cents (e.g., 1000 for $10.00)
currency string Yes Three-letter currency code (e.g., USD, EUR)
payment_method string Yes Payment method type (card, bank_transfer)
card_number string Yes* Card number (required for card payments)
cvv string Yes* Card security code
customer_info object No Customer information
metadata object No Additional data to store

Request Example

Process Direct Payment 
{
  "amount": 15000,
  "currency": "USD",
  "payment_method": "card",
  "card_number": "4242424242424242",
  "expiry_month": "12",
  "expiry_year": "2025",
  "cvv": "123",
  "customer_info": {
    "name": "John Doe",
    "email": "john@example.com",
    "phone": "+1234567890",
    "address": {
      "line1": "123 Main St",
      "city": "New York",
      "state": "NY",
      "postal_code": "10001",
      "country": "US"
    }
  },
  "metadata": {
    "order_id": "ORD-12345",
    "product": "Premium Plan"
  },
  "webhook_url": "https://your-site.com/webhooks/payment",
  "return_url": "https://your-site.com/payment/3ds-return"
}

Success Response

Payment Successful 
{
  "success": true,
  "message": "Payment processed successfully",
  "data": {
    "transaction_id": "txn_ABC123DEF456",
    "amount": 15000,
    "currency": "USD",
    "status": "completed",
    "gateway_transaction_id": "gw_XYZ789",
    "created_at": "2025-07-23T07:11:23Z",
    "webhook_queued": true
  }
}

3DS Response

3DS Authentication Required 
{
  "success": true,
  "message": "3D Secure authentication required",
  "data": {
    "transaction_id": "txn_ABC123DEF456",
    "amount": 15000,
    "currency": "USD",
    "status": "pending",
    "gateway_transaction_id": "gw_XYZ789",
    "requires_action": true,
    "action_type": "3ds_authentication",
    "action_data": {
      "3ds_url": "https://pay.example.com/3ds/txn_ABC123DEF456"
    },
    "created_at": "2025-07-23T07:11:23Z",
    "webhook_queued": false
  }
}
POST /api/direct-payment/{transaction_id}/confirm-3ds

Confirm 3D Secure authentication for a pending transaction.

Request Parameters

Parameter Type Required Description
transaction_id string Yes Transaction ID from URL parameter
status string Yes 3DS status (success, failed, pending)
gateway_id string Yes Gateway transaction ID

Response Example

3DS Confirmation Success 
{
  "success": true,
  "message": "3D Secure authentication confirmed",
  "data": {
    "transaction_id": "txn_ABC123DEF456",
    "status": "completed",
    "gateway_transaction_id": "gw_XYZ789",
    "webhook_queued": true
  }
}
GET /api/direct-payment/{transaction_id}/status

Retrieve the current status of a transaction.

Response Example

Transaction Status 
{
  "success": true,
  "data": {
    "transaction_id": "txn_ABC123DEF456",
    "amount": 15000,
    "currency": "USD",
    "status": "completed",
    "gateway_transaction_id": "gw_XYZ789",
    "created_at": "2025-07-23T07:11:23Z",
    "processed_at": "2025-07-23T07:11:25Z",
    "customer_info": {
      "name": "John Doe",
      "email": "john@example.com"
    },
    "metadata": {
      "order_id": "ORD-12345"
    }
  }
}

Error Responses

Error Code HTTP Status Description
invalid_card 400 Card number is invalid
card_declined 400 Card was declined by the bank
insufficient_funds 400 Insufficient funds on the card
expired_card 400 Card has expired
invalid_cvv 400 CVV is incorrect
3ds_required 202 3D Secure authentication required
transaction_not_found 404 Transaction does not exist
rate_limit_exceeded 429 Too many requests, try again later

Hosted Payment API

Create secure, hosted payment pages that handle sensitive payment data. Perfect for businesses that want to minimize PCI compliance requirements.

PCI Compliant

Minimal PCI scope

Customizable

Branded payment pages

Mobile Optimized

Responsive design

Global Ready

Multi-currency support

POST /api/hosted-payment/create

Create a hosted payment session that customers can use to complete their payment.

Request Parameters

Parameter Type Required Description
amount integer Yes Amount in cents (e.g., 1000 for $10.00)
currency string Yes Three-letter currency code (e.g., USD, EUR)
description string Yes Payment description shown to customer
customer_info object No Pre-filled customer information
metadata object No Additional data to store
webhook_url string No URL to receive payment notifications
return_url string No URL to redirect after payment
expires_at string No ISO 8601 timestamp for expiration

Request Example

Create Hosted Payment Session 
{
  "amount": 25000,
  "currency": "USD",
  "description": "Premium Subscription - Annual Plan",
  "customer_info": {
    "name": "Jane Smith",
    "email": "jane@example.com",
    "phone": "+1234567890"
  },
  "metadata": {
    "subscription_id": "sub_12345",
    "plan_type": "premium_annual"
  },
  "webhook_url": "https://your-site.com/webhooks/payment",
  "return_url": "https://your-site.com/payment/success",
  "expires_at": "2025-08-23T23:59:59Z"
}

Success Response

Payment Session Created
{
  "success": true,
  "message": "Payment session created successfully",
  "data": {
    "session_id": "sess_ABC123DEF456",
    "payment_url": "https://pay.example.com/sess_ABC123DEF456",
    "amount": 25000,
    "currency": "USD",
    "description": "Premium Subscription - Annual Plan",
    "status": "pending",
    "expires_at": "2025-08-23T23:59:59Z",
    "created_at": "2025-07-23T07:11:23Z"
  }
}
GET /api/hosted-payment/{session_id}/status

Check the current status of a hosted payment session.

Response Example

Session Status 
{
  "success": true,
  "data": {
    "session_id": "sess_ABC123DEF456",
    "amount": 25000,
    "currency": "USD",
    "description": "Premium Subscription - Annual Plan",
    "status": "completed",
    "transaction_id": "txn_XYZ789",
    "customer_info": {
      "name": "Jane Smith",
      "email": "jane@example.com"
    },
    "created_at": "2025-07-23T07:11:23Z",
    "completed_at": "2025-07-23T07:15:45Z"
  }
}
DELETE /api/hosted-payment/{session_id}

Cancel an active payment session before it expires.

Response Example

Session Cancelled 
{
  "success": true,
  "message": "Payment session cancelled successfully",
  "data": {
    "session_id": "sess_ABC123DEF456",
    "status": "cancelled",
    "cancelled_at": "2025-07-23T08:30:00Z"
  }
}

3D Secure Support

Our hosted payment pages automatically handle 3D Secure authentication when required by the card issuer.

3D Secure Flow

  1. Customer enters card details on the hosted page
  2. If 3DS is required, customer is redirected to their bank
  3. After authentication, customer returns to your return URL
  4. Payment is processed and webhook is sent

Error Responses

Error Code HTTP Status Description
invalid_amount 400 Amount is invalid or below minimum
invalid_currency 400 Currency code is not supported
session_not_found 404 Payment session does not exist
session_expired 410 Payment session has expired
session_already_completed 409 Payment session is already completed
invalid_webhook_url 400 Webhook URL is invalid
invalid_return_url 400 Return URL is invalid

Webhooks

Webhooks allow you to receive real-time notifications about payment events. Configure your webhook URL in your dashboard to start receiving notifications.

Webhook Events

Event Description Data
payment.succeeded Payment completed successfully Transaction details, amount, customer info
payment.failed Payment failed or was declined Error details, failure reason
payment.pending Payment is pending (e.g., 3DS authentication) Transaction details, pending status

Webhook Security

All webhook requests include a signature header that you can verify to ensure the request is legitimate.

Webhook Signature Verification 
// Verify webhook signature
$signature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'];
$payload = file_get_contents('php://input');
$expected = hash_hmac('sha256', $payload, $webhook_secret);

if (hash_equals($expected, $signature)) {
    // Webhook is legitimate
    $data = json_decode($payload, true);
    // Process webhook data
} else {
    // Invalid signature
    http_response_code(400);
    exit('Invalid signature');
}

Testing

Use our test environment to develop and test your integration before going live.

Test Cards

Card Number Result Description
4242424242424242 Success Visa card that will always succeed
4000000000000002 Declined Card that will always be declined
4000000000003220 3DS Required Card that requires 3D Secure authentication

Test Environment

Use the test API endpoint: https://api-test.example.com

Error Handling

Handle errors gracefully by checking the response status and error details.

Error Response Format

Error Response Example 
{
  "error": {
    "code": "card_declined",
    "message": "Your card was declined.",
    "type": "card_error",
    "decline_code": "insufficient_funds"
  }
}

Common Error Codes

Error Code HTTP Status Description
invalid_request 400 The request was invalid
authentication_failed 401 Invalid API key
rate_limit_exceeded 429 Too many requests
server_error 500 Internal server error

Security

We take security seriously and implement industry best practices to protect your data.

PCI Compliance

Our platform is PCI DSS Level 1 compliant, the highest level of certification available in the payments industry.

Data Encryption

  • All data is encrypted in transit using TLS 1.3
  • Sensitive data is encrypted at rest using AES-256
  • API keys are hashed using bcrypt

Fraud Protection

Our advanced fraud detection system analyzes transactions in real-time to identify and prevent fraudulent activity.

Rate Limits

To ensure fair usage and system stability, we implement rate limits on our API endpoints.

Rate Limit Headers

All API responses include rate limit headers:

Rate Limit Headers 
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640995200

Default Limits

  • Authentication endpoints: 10 requests per minute
  • Payment endpoints: 100 requests per minute
  • Webhook endpoints: 1000 requests per minute

Changelog

Track the latest updates and improvements to our API.

Version 2.0.0 - 2025-01-15

  • Added support for 3D Secure 2.0
  • Improved webhook reliability
  • Enhanced error messages
  • New fraud detection features

Version 1.9.0 - 2024-12-01

  • Added support for Apple Pay and Google Pay
  • Improved rate limiting
  • Enhanced documentation