POST /api/v1/card-collection Visa • Mastercard

Card Checkout (USD)

Generate secure, hosted 3D-Secure credit and debit card checkout sessions for customers anywhere in the world paying in USD.

Request Parameters (JSON Body)

Parameter	Type	Required	Description
amount	number	Required	The amount to charge in USD (e.g. `25.00`). Min $1.00.
currency	string	Required	Set to `USD`.
name	string	Required	Customer full name for cardholder verification.
email	string	Required	Customer email address for card payment receipts.
reference	string	Optional	Your unique internal invoice reference ID.
return_url	string	Optional	Redirect URL where customer is sent after completing or cancelling checkout.

Code Example

curl -X POST https://hivepay.site/api/v1/card-collection \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -H "X-Account-Number: YOUR_ACCOUNT_NUMBER" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 25.00,
    "currency": "USD",
    "name": "Jane Doe",
    "email": "[email protected]",
    "reference": "CRD-1001",
    "description": "Premium Subscription",
    "return_url": "https://yourdomain.com/checkout/success"
  }'

<?php
$payload = [
    'amount'      => 25.00,
    'currency'    => 'USD',
    'name'        => 'Jane Doe',
    'email'       => '[email protected]',
    'reference'   => 'CRD-1001',
    'description' => 'Premium Subscription',
    'return_url'  => 'https://yourdomain.com/checkout/success'
];

$ch = curl_init('https://hivepay.site/api/v1/card-collection');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => json_encode($payload),
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'X-API-Key: ' . getenv('HIVEPAY_API_KEY'),
        'X-API-Secret: ' . getenv('HIVEPAY_API_SECRET'),
        'X-Account-Number: ' . getenv('HIVEPAY_ACCOUNT_NO'),
        'Content-Type: application/json'
    ]
]);

$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);
if ($result['success'] && !empty($result['checkout_url'])) {
    // Redirect customer to the secure card payment page
    header('Location: ' . $result['checkout_url']);
    exit;
}

const response = await fetch('https://hivepay.site/api/v1/card-collection', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.HIVEPAY_API_KEY,
    'X-API-Secret': process.env.HIVEPAY_API_SECRET,
    'X-Account-Number': process.env.HIVEPAY_ACCOUNT_NO,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    amount: 25.00,
    currency: 'USD',
    name: 'Jane Doe',
    email: '[email protected]',
    reference: 'CRD-1001',
    description: 'Premium Subscription',
    return_url: 'https://yourdomain.com/checkout/success'
  })
});

const data = await response.json();
console.log('Redirect client to:', data.checkout_url);

import os, requests

payload = {
    'amount': 25.00,
    'currency': 'USD',
    'name': 'Jane Doe',
    'email': '[email protected]',
    'reference': 'CRD-1001',
    'description': 'Premium Subscription',
    'return_url': 'https://yourdomain.com/checkout/success'
}

res = requests.post(
    'https://hivepay.site/api/v1/card-collection',
    json=payload,
    headers={
        'X-API-Key': os.getenv('HIVEPAY_API_KEY'),
        'X-API-Secret': os.getenv('HIVEPAY_API_SECRET'),
        'X-Account-Number': os.getenv('HIVEPAY_ACCOUNT_NO'),
        'Content-Type': 'application/json'
    }
)
data = res.json()
print("Card Checkout URL:", data.get('checkout_url'))

Response (200 OK)

Response JSON

{
  "success": true,
  "message": "Card checkout session created successfully.",
  "reference": "CRD-1001",
  "gateway_reference": "HP-CRD-9876543210",
  "checkout_url": "https://checkout.hivepay.co/pay?session=hp_chk_...",
  "amount": 25,
  "currency": "USD",
  "status": "pending"
}

← Collect Money Next: Send Money (Payouts)