Skip to content

How to Accept Credit Card Payments on Your Website Using the 4Geeks Payments API

🤖 Explain with AI

The 4Geeks Payments API empowers developers to build fully customizable checkout experiences. Whether you are running a simple e-commerce store or a complex SaaS platform, this API allows you to process credit cards, debit cards, and digital wallet transactions directly from your application.

This guide provides a step-by-step walkthrough to integrating the Payments API, ensuring secure and efficient transaction processing.

Prerequisites

Before writing any code, ensure you have the following ready:

  • Verified 4Geeks Account: You must have access to the 4Geeks Console.
  • Active Payments Service: Ensure the Payments module is enabled in your account settings.
  • API Credentials: You will need your Client ID and Client Secret (or API Keys) from the developer dashboard.
  • SSL Certificate: Your website must serve content over HTTPS to securely handle transaction data.

Step-by-Step Instructions

Follow these steps to process a standard payment charge using the API.

Step 1: Obtain Your API Credentials

To communicate with the API, you first need to retrieve your secure credentials.

  1. Log in to the 4Geeks Console.
  2. Navigate to Settings > API Keys in the side menu.
  3. Locate your Client ID and Client Secret.

Tip: You will see two sets of keys: “Test” and “Live”. Always use Test keys during development to simulate transactions without moving real money. Switch to Live keys only when you are ready to launch.

Step 2: Generate an Access Token

The 4Geeks API uses Bearer Token authentication. You must exchange your credentials for a temporary access token before making payment requests.

Endpoint: POST /oauth/token

Request Body: 

    {
        "client_id": "YOUR_CLIENT_ID",
        "client_secret": "YOUR_CLIENT_SECRET",
        "grant_type": "client_credentials"
    }

Response: The API will return a JSON object containing an access_token. You will use this token in the header of your subsequent requests.

Step 3: Create a Payment Charge

Now that you are authenticated, you can initiate a transaction. This request sends the payment details to 4Geeks for processing.

Endpoint: POST /v1/payments/

Headers:

  • Authorization: Bearer <YOUR_ACCESS_TOKEN>
  • Content-Type: application/json

Body Parameters:

  • amount: The total cost (e.g., 150.00).
  • currency: The 3-letter ISO code (e.g., USD, EUR).
  • description: A brief summary of the purchase.
  • return_url: The URL where your customer will be redirected after the payment process (essential for 3D Secure flows).

Example Request:

{
  "amount": 150.00,
  "currency": "USD",
  "description": "Annual Premium Subscription",
  "return_url": "[https://your-website.com/checkout/success](https://your-website.com/checkout/success)"
}

Step 4: Handle the Response

The API will return the status of the transaction immediately.

  • Success: If the status is succeeded or approved, the payment is complete. You should show a success message to the user and update your database.
  • Action Required: If the status is action_required (common with 3D Secure), the response will include a redirect_url. You must redirect the customer to this URL to complete bank verification.

Common Use Cases

1. E-commerce Checkout

A customer adds items to their cart and clicks “Checkout.” Your backend calculates the total and calls the /v1/payments/ endpoint. Upon a successful response, you trigger your inventory system (perhaps managed by 4Geeks Asset) to deduct stock and send a confirmation email.

2. SaaS Subscription Billing

For a monthly software service, you can tokenize a customer’s card during their first payment. You can then use that token to automate future charges via the API without asking the user to re-enter their details every month. This integrates seamlessly with 4Geeks Payments recurring billing features.

Troubleshooting

Here are solutions to common errors you might encounter during integration:

  • 401 Unauthorized Error:
  • Cause: Your Bearer Token is missing, incorrect, or has expired.

  • Solution: Regenerate a new token using the /oauth/token endpoint and ensure it is included correctly in the Authorization header.

  • Transaction Declined (Generic Error):

  • Cause: The card issuer rejected the transaction (e.g., insufficient funds).

  • Solution: Check the error_code in the API response. If you are in Test Mode, ensure you are using the valid test card numbers provided in the documentation.

  • CORS Error:

  • Cause: You are trying to make API calls directly from the browser (client-side).
  • Solution: For security, never expose your Client Secret in frontend code. Always route payment requests through your own backend server.

Conclusion

Integrating the 4Geeks Payments API gives you full control over your payment flows, allowing for a secure and customized experience for your users. By following these steps, you can start accepting credit cards safely and efficiently.

For more advanced configurations, such as saving cards for future use or handling webhooks, visit the 4Geeks Console or explore our developer documentation.

Additional Resources