Pay-in (Card) API

This endpoint allows you to initiate card payment requests from your customers. After successful processing, funds will be credited to your Zikopay wallet.

Endpoint

POST /payments/payin/card

Headers

Name	Description
X-API-Key	Your Zikopay API Key
X-API-Secret	Your Zikopay API Secret
Accept	Must be application/json
Content-Type	Must be application/json

Request Parameters

Parameter	Type	Required	Description
amount	number	Yes	Transaction amount in the specified currency
currency	string	Yes	Currency code (e.g., XAF, NGN, GHS)
operator	string	Yes	Card operator (e.g., visa, mastercard)
return_url	string	Yes	URL where customer will be redirected after payment
cancel_url	string	Yes	URL where customer will be redirected if they cancel
callback_url	string	Yes	URL where payment status updates will be sent
description	string	Yes	Transaction description
payment_details	object	No	Additional payment metadata
customer	object	Yes	Customer information
customer.name	string	Yes	Customer's full name
customer.phone	string	Yes	Customer's phone number
customer.email	string	Yes	Customer's email address

Example Request

{
  "amount": 200,
  "currency": "XAF",
  "operator": "visa",
  "return_url": "https://yourwebsite.com/payment/success",
  "cancel_url": "https://yourwebsite.com/payment/cancel",
  "callback_url": "https://yourwebsite.com/api/webhook",
  "description": "Payment for order #12345",
  "payment_details": {
    "order_id": "12345",
    "items": "Premium subscription"
  },
  "customer": {
    "name": "John Doe",
    "phone": "696447002",
    "email": "john.doe@example.com"
  }
}

Success Response

{
    "error": false,
    "reference": "TXN17494044248E915E",
    "payment_url": "https://api.payment.zikopay.com/payment/BLA2",
    "status": "success",
    "error_message": null
}

Error Response

{
    "error": true,
    "reference": "TXN17494044248E915E",
    "status": "success",
    "error_message": "Something went wrong"
}

Response Parameters

Parameter	Type	Description
reference	string	Unique transaction reference ID
amount	number	Transaction amount
currency	string	Transaction currency
status	string	Current transaction status: pending, completed, failed
payment_url	string	URL where the customer should be redirected to complete payment
expires_at	string	ISO8601 timestamp when the payment request will expire

Transaction Flow

1. Your application calls this endpoint to initialize a card payment
2. You redirect the customer to the payment_url returned in the response
3. Customer enters their card details and completes the payment
4. Zikopay redirects the customer back to your return_url
5. Zikopay sends a webhook notification to your callback_url with the final payment status

Supported Card Operators

Operator	Code	Payment Type	Countries	Currencies
Visa	visa	Card	US, France	USD, EUR
Mastercard	mastercard	Card	US, France	USD, EUR

Testing

In the test environment, you can use the following test cards:

Card Number	Expiry	CVV	Result
4242 4242 4242 4242	Any future date	Any 3 digits	Successful payment
4000 0000 0000 0002	Any future date	Any 3 digits	Declined payment

Notes

• Card payments are subject to the standard processing fee as per your merchant agreement
• Checkout pages expire after 30 minutes
• All amounts should be provided in the smallest unit of the currency (e.g., cents, kobo)

Code Examples

PHP

<?php
$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.payment.zikopay.com/v1/payments/payin/card",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'amount' => 200,
    'currency' => 'XAF',
    'operator' => 'visa',
    'return_url' => 'https://yourwebsite.com/payment/success',
    'cancel_url' => 'https://yourwebsite.com/payment/cancel',
    'callback_url' => 'https://yourwebsite.com/api/webhook',
    'description' => 'Payment for order #12345',
    'payment_details' => [
      'order_id' => '12345'
    ],
    'customer' => [
      'name' => 'John Doe',
      'phone' => '696447002',
      'email' => 'john.doe@example.com'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Accept: application/json",
    "Content-Type: application/json",
    "X-API-Key: your_api_key",
    "X-API-Secret: your_api_secret"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  $data = json_decode($response, true);
  // Redirect user to checkout URL
  if ($data['success']) {
    header('Location: ' . $data['data']['payment_url']);
    exit;
  }
}
?>

JavaScript

const initiateCardPayment = async () => {
    try {
        const response = await fetch('https://api.payment.zikopay.com/v1/payments/payin/card', {
            method: 'POST',
            headers: {
                'Accept': 'application/json',
                'Content-Type': 'application/json',
                'X-API-Key': 'your_api_key',
                'X-API-Secret': 'your_api_secret'
            },
            body: JSON.stringify({
                amount: 200,
                currency: 'XAF',
                operator: 'visa',
                return_url: 'https://yourwebsite.com/payment/success',
                cancel_url: 'https://yourwebsite.com/payment/cancel',
                callback_url: 'https://yourwebsite.com/api/webhook',
                description: 'Payment for order #12345',
                payment_details: {
                    order_id: '12345'
                },
                customer: {
                    name: 'John Doe',
                    phone: '696447002',
                    email: 'john.doe@example.com'
                }
            })
        });

        const data = await response.json();

        if (data.success) {
            // Redirect customer to the checkout URL
            window.location.href = data.data.payment_url;
        } else {
            console.error('Payment initiation failed:', data.message);
        }
    } catch (error) {
        console.error('Error:', error);
    }
};

Python

import requests
import json

url = "https://api.payment.zikopay.com/v1/payments/payin/card"

payload = json.dumps({
  "amount": 200,
  "currency": "XAF",
  "operator": "visa",
  "return_url": "https://yourwebsite.com/payment/success",
  "cancel_url": "https://yourwebsite.com/payment/cancel",
  "callback_url": "https://yourwebsite.com/api/webhook",
  "description": "Payment for order #12345",
  "payment_details": {
    "order_id": "12345"
  },
  "customer": {
    "name": "John Doe",
    "phone": "696447002",
    "email": "john.doe@example.com"
  }
})

headers = {
  'Accept': 'application/json',
  'Content-Type': 'application/json',
  'X-API-Key': 'your_api_key',
  'X-API-Secret': 'your_api_secret'
}

response = requests.post(url, headers=headers, data=payload)

if response.status_code == 200:
    data = response.json()
    if data['success']:
        # Redirect the user to the checkout URL
        checkout_url = data['data']['payment_url']
        print(f"Redirect user to: {checkout_url}")
    else:
        print(f"Error: {data['message']}")
else:
    print(f"HTTP Error: {response.status_code}")