Cards API

The Cards API allows you to accept card payments from your customers through our hosted checkout system. This provides a secure, PCI-compliant way to collect card payments without handling sensitive card data directly.

Overview

Our hosted checkout system provides a seamless payment experience:

1. Initialize Payment: Call the initialize API to create a payment session and receive a unique checkout URL
2. Redirect Customer: Send your customer to the hosted checkout URL
3. Customer Completes Payment: Customer enters their card details and completes the transaction on our secure checkout page
4. Webhook Notification: Receive payment status updates via webhooks

Benefits

• PCI Compliance: We handle all card data, so you don't need PCI DSS certification
• 3D Secure Support: Automatic handling of 3D Secure authentication
• Secure: All card data is encrypted and never touches your servers
• Easy Integration: Simple API calls to get started

Initialize Payment

Create a payment session and receive a checkout URL where your customer can complete their payment.

Endpoint

POST /api/v1/client/card/payment/initialize

Authentication

This endpoint requires HMAC authentication. Include your API key and signature in the request headers:

x-api-key: <your-api-key>
x-timestamp: <rfc3339-timestamp>
x-signature: <hmac-sha256-signature>

Request Body

{
  "email": "customer@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "amount": "1000.00",
  "currency": "NGN",
  "reference": "ORDER-12345",
  "redirectUrl": "https://your-website.com/payment-success",
  "logoUrl": "https://your-website.com/logo.png",
  "description": "Payment for order #12345",
  "customer_phone_number": "+2348012345678"
}

Request Parameters

Success Response (201 Created)

{
  "success": true,
  "message": "Transaction Initialized Successfully",
  "data": {
    "access_code": "AbCdEfGhIjKlMnOpQrStUv",
    "checkout_link": "https://checkout.transfaar.com/checkout/AbCdEfGhIjKlMnOpQrStUv",
    "transactionRef": "TXN-123456789",
    "reference": "ORDER-12345",
    "redirectUrl": "https://your-website.com/payment-success"
  }
}

Response Fields

Error Responses

400 Bad Request - Invalid request data

{
  "error": "missing required fields: email, first_name, last_name, amount, currency, and reference are required"

401 Unauthorized - Invalid or missing authentication

{
  "error": "unauthorized"
}

Integration Flow

Step 1: Initialize Payment

When a customer is ready to pay, call the initialize endpoint with their details:

curl -X POST https://api.transfaar.com/api/v1/client/card/payment/initialize \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key" \
  -H "x-timestamp: 2025-01-15T10:30:00Z" \
  -H "x-signature: your-hmac-signature" \
  -d '{
    "email": "customer@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "amount": "1000.00",
    "currency": "NGN",
    "reference": "ORDER-12345",
    "redirectUrl": "https://your-website.com/payment-success",
    "description": "Payment for order #12345"
  }'

Step 2: Redirect Customer to Hosted Checkout

After receiving the response, redirect your customer to the checkout_link URL. This will take them to our secure hosted checkout page where they can complete their payment.

// Example: Server-side redirect (Node.js/Express)
app.post('/initiate-payment', async (req, res) => {
  const initResponse = await initializeCardPayment({
    email: req.body.email,
    first_name: req.body.first_name,
    last_name: req.body.last_name,
    amount: req.body.amount,
    currency: req.body.currency,
    reference: req.body.reference,
    redirectUrl: 'https://your-website.com/payment-success'
  });
  
  if (initResponse.success) {
    // Redirect customer to hosted checkout
    res.redirect(initResponse.data.checkout_link);
  } else {
    res.status(400).json({ error: initResponse.error });
  }
});

Step 3: Customer Completes Transaction on Hosted Checkout

On the hosted checkout page, your customer will:

1. See the payment details (amount, currency, description)
2. Enter their card details securely (card number, CVV, expiry date)
3. Complete 3D Secure authentication if required by their bank
4. Complete the payment transaction
5. Be automatically redirected back to your redirect_url upon completion

Step 4: Receive Webhook Notification

You'll receive a webhook notification with the payment status. Configure your webhook URL in your business settings to receive real-time payment status updates.

Webhook Events

You'll receive webhook notifications for payment status changes. The webhook payload includes:

{
  "transaction_reference": "TXN-123456789",
  "transaction_status": "successful",
  "amount": "1000.00",
  "currency": "NGN",
  "reference": "ORDER-12345",
  "status": "completed"
}

For more details on webhook handling, see the Webhooks documentation.

Best Practices

1. Store Transaction References

Always store the transactionRef returned from the initialize endpoint. This allows you to:

• Track payment status
• Reconcile payments with your orders
• Handle webhook notifications
• Look up payment details later

2. Set Appropriate Redirect URLs

Use your redirectUrl to:

• Show payment success/failure pages
• Update order status in your system
• Send confirmation emails to customers
• Provide a seamless return experience for customers

3. Handle Webhooks

Don't rely solely on redirect URLs for payment confirmation. Always verify payment status via webhooks, as customers may close their browser before redirect.

4. Validate Amounts

Ensure the amount matches what the customer expects. The checkout page will display the amount, but it's good practice to verify in your system.

5. Error Handling

Handle initialization errors gracefully:

• Invalid amounts (must be greater than zero)
• Invalid currency codes
• Missing required fields
• Authentication failures

Example: Complete Integration

Here's a complete example of integrating card payments:

async function processCardPayment(orderData) {
  try {
    // Step 1: Initialize payment
    const initResponse = await initializePayment({
      email: orderData.customerEmail,
      first_name: orderData.customerFirstName,
      last_name: orderData.customerLastName,
      amount: orderData.amount.toFixed(2),
      currency: orderData.currency,
      reference: orderData.orderId,
      redirectUrl: `https://your-website.com/orders/${orderData.orderId}/payment-complete`,
      description: `Payment for order #${orderData.orderId}`
    });
 
    if (initResponse.success) {
      // Step 2: Store transaction reference
      await saveTransactionReference(orderData.orderId, initResponse.data.transactionRef);
      
      // Step 3: Redirect to hosted checkout
      window.location.href = initResponse.data.checkout_link;
    } else {
      throw new Error(initResponse.error || 'Failed to initialize payment');
    }
  } catch (error) {
    console.error('Payment initialization failed:', error);
    showErrorMessage('Failed to start payment. Please try again.');
  }
}
 
async function initializePayment(paymentData) {
  const timestamp = new Date().toISOString();
  const signature = generateHMACSignature(JSON.stringify(paymentData), timestamp);
  
  const response = await fetch('https://api.transfaar.com/api/v1/client/card/payment/initialize', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': YOUR_API_KEY,
      'x-timestamp': timestamp,
      'x-signature': signature
    },
    body: JSON.stringify(paymentData)
  });
  
  return await response.json();
}

Security Considerations

• Never store card data: Our hosted checkout handles all card data securely
• Use HTTPS: Always use HTTPS for all API calls
• Verify webhooks: Always verify webhook signatures before processing
• Protect API keys: Keep your API keys secure and never expose them in client-side code
• Validate amounts: Always validate payment amounts on your server before initializing

Supported Currencies

Card payments are currently supported for:

• NGN (Nigerian Naira)
• USD (US Dollar)

Additional currencies may be added in the future.

Support

For questions or issues with card payments, contact our support team.