Live Pay

LivePay

Card Collection API

Accept credit and debit card payments from customers worldwide

Overview

The Card Collection API allows you to accept credit and debit card payments from customers worldwide. Funds are added to your balance when the transaction is successful.

Endpoint

https://livepay.me/api/card-collection

Method: POST

Important Notes

  • Only USD currency is supported for card payments
  • Minimum amount: $1.00
  • Maximum amount: $5,000.00
  • return_url must be a public http(s) URL

Quick Start

Request Example

Terminal
curl "https://livepay.me/api/card-collection" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <keyId>.<secret>" \
  -d '{
    "accountNumber": "LP2305443309",
    "amount": 50.00,
    "currency": "USD",
    "reference": "INVOICE123456789",
    "email": "[email protected]",
    "description": "Payment for invoice #12345",
    "return_url": "https://your-website.com/payment-success"
  }'

Authentication

All API requests require Bearer token authentication using your API key in the Authorization header.

Headers

Authorization

Bearer <keyId>.<secret>

Content-Type

application/json

API Key Format

Your API key is a dot-separated pair: keyId.secret. Pass the entire string after Bearer.

Request Parameters

Parameter Type Required Description
accountNumber String Yes Your account number
amount Number Yes Amount in USD (min: $1.00, max: $5,000.00)
currency String Yes Must be USD
reference String Yes Unique reference ID (no spaces, max 30 chars)
email String Yes Customer's email address
description String Yes Transaction description
return_url String Optional Redirect URL after successful payment. Must be public http(s).

Response Format

Success Response (200 OK)

success.json
{
  "success": true,
  "message": "Card transaction created successfully",
  "checkout_url": "https://partners.livepay.me/checkout?ref=REF-MVE60LII-DVFWSB",
  "reference": "REF-MVE60LII-DVFWSB",
  "internal_reference": "c33fafc4-e0b6-4235-bf1b-319cc6271b64"
}

Payment Flow

Redirect your customer to the checkout_url to complete the payment. On success, Bachs redirects them to your return_url with ?checkout_id= appended.

Error Responses

Status Code Error Message Description
400 Missing required fields Required field missing
400 Card payments are currently USD only Non-USD currency provided
400 Invalid amount Amount is not a valid number
400 Amount must be at least 1 USD Amount below minimum
400 Amount must not exceed 5,000 USD Amount above maximum
400 Reference already used Duplicate reference ID
400 Reference must not contain spaces Reference has spaces
400 Reference must be at most 30 characters Reference too long
400 return_url must be a public http(s) URL Invalid return_url
401 Authorization required Missing Authorization header
401 Invalid API key Invalid API key
403 Account number does not match API key owner Account mismatch
429 Too many requests Rate limit exceeded (500 per 15 min)
500 Internal server error Server error
502 Card service unavailable Payment provider unavailable
503 Collections are currently disabled. Please try again later. Collections globally disabled
504 Card service timeout. Please try again. Payment provider timeout

Code Examples

javascript.js
async function createCardTransaction(apiKey, data) {
    const response = await fetch('https://livepay.me/api/card-collection', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
            'Authorization': `Bearer ${apiKey}`
        },
        body: JSON.stringify({
            accountNumber: data.accountNumber,
            amount: data.amount,
            currency: 'USD',
            reference: data.reference,
            email: data.email,
            description: data.description,
            return_url: data.return_url || 'https://your-website.com/success'
        })
    });
    
    if (!response.ok) {
        const error = await response.json();
        throw new Error(error.error || 'Payment creation failed');
    }
    
    return await response.json();
}