Payment Gateway API Documentation

This documentation describes the RESTful API for integrating with our Payment Gateway. The API allows merchants to initialize payments, check transaction status, and process refunds.

Authentication

All API requests must be authenticated using your API key and secret provided by the payment gateway.

Security Note: Always keep your API Secret secure and never expose it in client-side code.

Include the following headers in your requests:

X-Api-Key: your_api_key
X-Api-Secret: your_api_secret

API Endpoints

The following endpoints are available for interacting with the Payment Gateway API:

Payment Provider Options

When initializing a payment, you can specify the payment provider using one of these approaches:

General Payment Provider

Use the base payment processor code:

• cybersource - For CyberSource payment processing
• mpgs - For Mastercard Payment Gateway Services

Initialize a Payment

Create a new payment transaction and get a redirect URL for the customer.

POST /api/v1/payments/initialize

Request Parameters:

Example Request (cURL):

curl -X POST "https://gateway.pesogate.com/api/v1/payments/initialize" \
                        -H "Content-Type: application/json" \
                        -H "X-Api-Key: your_api_key" \
                        -H "X-Api-Secret: your_api_secret" \
                        -d '{
                            "order_id": "ORDER123456",
                            "amount": 100.50,
                            "currency": "USD",
                            "payment_provider": "mpgs",
                            "card_number": "4111111111111111",
                            "exp_month": "12",
                            "exp_year": "25",
                            "cvv": "123",
                            "customer_email": "customer@example.com",
                            "customer_name": "John Doe",
                            "return_url": "https://your-website.com/payment/success",
                            "cancel_url": "https://your-website.com/payment/cancel"
                        }'

Initialize a Payment

Create a new payment transaction and get a redirect URL for the customer.

POST /api/v1/payments/initialize

Request Parameters:

Example Request (cURL):

curl -X POST "https://gateway.pesogate.com/api/v1/payments/initialize" \
-H "Content-Type: application/json" \
-H "X-Api-Key: your_api_key" \
-H "X-Api-Secret: your_api_secret" \
-d '{
    "order_id": "ORDER123456",
    "amount": 100.50,
    "currency": "USD",
    "payment_provider": "mpgs",
    "card_number": "4111111111111111",
    "exp_month": "12",
    "exp_year": "25",
    "cvv": "123",
    "customer_email": "customer@example.com",
    "customer_name": "John Doe",
    "return_url": "https://your-website.com/payment/success",
    "cancel_url": "https://your-website.com/payment/cancel"
}'

Example Request (PHP):

<?php
$apiKey = 'your_api_key';
$apiSecret = 'your_api_secret';
$url = 'https://gateway.pesogate.com/api/v1/payments/initialize';

$data = [
    'order_id' => 'ORDER123456',
    'amount' => 100.50,
    'currency' => 'USD',
    'payment_provider' => 'mpgs',
    'card_number' => '4111111111111111',
    'exp_month' => '12',
    'exp_year' => '25',
    'cvv' => '123',
    'customer_email' => 'customer@example.com',
    'customer_name' => 'John Doe',
    'return_url' => 'https://your-website.com/payment/success',
    'cancel_url' => 'https://your-website.com/payment/cancel'
];

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'X-Api-Key: ' . $apiKey,
    'X-Api-Secret: ' . $apiSecret
]);

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

$result = json_decode($response, true);
?>

Success Response (200 OK):

{
    "success": true,
    "message": "Transaction initialized successfully",
    "redirect_url": "https://checkout.payment-gateway.com/abc123",
    "transaction_reference": "550e8400-e29b-41d4-a716-446655440000"
}

Error Response (422 Unprocessable Entity):

{
    "success": false,
    "message": "Validation failed",
    "errors": {
        "amount": ["The amount field is required."]
    }
}

Check Transaction Status

Check the status of an existing transaction.

GET /api/v1/payments/{referenceId}/status

URL Parameters:

Example Request (cURL):

curl -X GET "https://gateway.pesogate.com/api/v1/payments/550e8400-e29b-41d4-a716-446655440000/status" \
-H "X-Api-Key: your_api_key" \
-H "X-Api-Secret: your_api_secret"

Example Request (PHP):

<?php
$apiKey = 'your_api_key';
$apiSecret = 'your_api_secret';
$referenceId = '550e8400-e29b-41d4-a716-446655440000';
$url = "https://gateway.pesogate.com/api/v1/payments/{$referenceId}/status";

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'X-Api-Key: ' . $apiKey,
    'X-Api-Secret: ' . $apiSecret
]);

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

$result = json_decode($response, true);
?>

Success Response (200 OK):

{
    "success": true,
    "message": "Transaction status retrieved",
    "data": {
        "status": "completed",
        "amount": 100.50,
        "currency": "USD",
        "order_id": "ORDER123456",
        "payment_method": "card",
        "card_type": "visa",
        "card_last_four": "1234",
        "created_at": "2025-05-10T12:30:45Z",
        "completed_at": "2025-05-10T12:32:15Z"
    }
}

Error Response (404 Not Found):

{
    "success": false,
    "message": "Transaction not found"
}

Refund a Transaction

Process a refund for a completed transaction.

POST /api/v1/payments/{referenceId}/refund

URL Parameters:

Request Parameters:

Example Request (cURL):

curl -X POST "https://gateway.pesogate.com/api/v1/payments/550e8400-e29b-41d4-a716-446655440000/refund" \
-H "Content-Type: application/json" \
-H "X-Api-Key: your_api_key" \
-H "X-Api-Secret: your_api_secret" \
-d '{
    "amount": 50.25
}'

Example Request (PHP):

<?php
$apiKey = 'your_api_key';
$apiSecret = 'your_api_secret';
$referenceId = '550e8400-e29b-41d4-a716-446655440000';
$url = "https://gateway.pesogate.com/api/v1/payments/{$referenceId}/refund";

$data = [
    'amount' => 50.25 // For partial refund
];

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'X-Api-Key: ' . $apiKey,
    'X-Api-Secret: ' . $apiSecret
]);

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

$result = json_decode($response, true);
?>

Success Response (200 OK):

{
    "success": true,
    "message": "Transaction refunded successfully",
    "transaction_reference": "550e8400-e29b-41d4-a716-446655440000"
}

Error Response (400 Bad Request):

{
    "success": false,
    "message": "Cannot refund transaction: Transaction is not in a completed state"
}

Transaction Statuses

The following statuses may be returned when checking a transaction:

Payment Flow

1. Initialization: Your system initializes a payment transaction by calling the /payments/initialize endpoint with the order details.
2. Redirection: The API returns a redirect_url where you should redirect your customer to complete the payment.
3. Payment Processing: The customer completes the payment at the payment provider's hosted checkout page.
4. Callback Processing: After the payment is processed, the customer is redirected back to your return_url or cancel_url based on the payment result.
5. Status Check: Your system should verify the payment status by calling the /payments/{referenceId}/status endpoint to confirm the transaction was successful.

Payment Provider Options

When initializing a payment, you can specify the payment provider using one of these approaches:

General Payment Provider

Use the base payment processor code:

• cybersource - For CyberSource payment processing
• mpgs - For Mastercard Payment Gateway Services

Initialize a Payment

Create a new payment transaction and get a redirect URL for the customer.

POST /api/v1/payments/initialize

Request Parameters:

Example Request (cURL):

curl -X POST "https://gateway.pesogate.com/api/v1/payments/initialize" \
                        -H "Content-Type: application/json" \
                        -H "X-Api-Key: your_api_key" \
                        -H "X-Api-Secret: your_api_secret" \
                        -d '{
                            "order_id": "ORDER123456",
                            "amount": 100.50,
                            "currency": "USD",
                            "payment_provider": "mpgs",
                            "card_number": "4111111111111111",
                            "exp_month": "12",
                            "exp_year": "25",
                            "cvv": "123",
                            "customer_email": "customer@example.com",
                            "customer_name": "John Doe",
                            "return_url": "https://your-website.com/payment/success",
                            "cancel_url": "https://your-website.com/payment/cancel"
                        }'

3DS Authentication

This payment gateway implements 3D Secure (3DS) authentication for all card payments to enhance security and reduce fraud. The 3DS flow is automatically handled by the payment providers (CyberSource and MPGS).

During the payment process, the customer may be redirected to their bank's authentication page to verify their identity. After authentication, they will be returned to the payment flow to complete the transaction.

3DS Flow

1. You initialize a payment transaction with our API.
2. We create the transaction and interact with the payment provider.
3. The payment provider initiates 3DS authentication.
4. The customer is redirected to the 3DS page hosted by their card issuer.
5. After authentication, the customer is redirected back to complete the payment.
6. The final status is updated, and the customer is redirected to your return URL.

3DS API Responses

When 3DS authentication is required, the API may respond in one of two ways:

• Redirect URL Response: The API provides a redirect_url that you should redirect the customer to.
• HTML Content Response: For more complex 3DS flows, the API may respond with HTML content that must be rendered to the customer. The response will include an action field with value render_html and an html_content field containing the HTML to be rendered.

Example 3DS HTML Content Response:

{
                            "success": true,
                            "message": "3DS authentication required",
                            "action": "render_html",
                            "html_content": "...",
                            "transaction_reference": "550e8400-e29b-41d4-a716-446655440000"
                        }

When receiving a response with action set to render_html, you should:

1. Render the provided HTML content to the customer.
2. After the 3DS process completes, the customer will be automatically redirected to your return_url or cancel_url depending on the authentication outcome.
3. Your system should then verify the payment status by calling the /payments/{referenceId}/status endpoint to confirm the final transaction status.

Error Handling

The API returns appropriate HTTP status codes along with error messages in the response body. Common error codes:

• 400 Bad Request: Invalid request parameters
• 401 Unauthorized: Invalid API credentials
• 404 Not Found: Resource not found
• 422 Unprocessable Entity: Validation error
• 429 Too Many Requests: Rate limit exceeded
• 500 Internal Server Error: Server error

Example error response:

{
    "success": false,
    "message": "Error message describing the issue",
    "errors": {
        "field_name": ["Validation error message"]
    }
}

Rate Limiting

API requests are limited to 100 requests per minute per merchant. If you exceed this limit, you will receive a 429 Too Many Requests response.

To handle rate limits, implement an exponential backoff strategy: wait progressively longer before retrying (e.g., 1s, 2s, 4s). Check the Retry-After header in the response for guidance on when to retry.

API Versioning

The current API version is v1, as indicated in the endpoint URLs (e.g., /api/v1/payments). New versions will be introduced for breaking changes, and older versions will be supported for at least 6 months after a new version is released. Deprecation notices will be communicated via email and the merchant dashboard.

Testing

We provide a sandbox environment for testing your integration. Contact support@gateway.pesogate.com to obtain test credentials and the sandbox URL.

Use the following test card details in the sandbox environment:

CyberSource Test Cards

MPGS Test Cards

Support

For technical support or questions about the API, please contact:

• Email: support@gateway.pesogate.com
• Phone: +1-555-123-4567
• Merchant Dashboard: Open a ticket