API Gateway

An API Gateway allows your system to communicate directly with third-party payment providers (like Stripe, PayPal, or Shurjopay). It automates the payment process by redirecting the user to a secure hosted checkout and verifying the result via a background handshake.

Directory & Class Naming

Root Path: pp-content/pp-modules/pp-gateways/
Folder Name: lowercase-with-hyphens (e.g., stripe-v2)
File Name: Must be class.php
Class Name: FolderName (PascalCase) + Gateway (e.g., StripeV2Gateway)

pp-gateways/
└── stripe-v2/
    ├── class.php
    └── assets/
        └── logo.jpg

Gateway Logic Flow

The API Gateway follows a three-step cycle to ensure payment integrity.

Initiation (process_payment): User clicks "Pay," and the system sends transaction data to the provider.
Redirection: The user is sent to the provider's website to enter card/account details.
Verification (callback or ipn): The provider sends the user back with a unique ID. Your system verifies this ID with the provider's server before marking the order as complete.

Core Methods

`info()`

Defines the metadata. The gateway_type must be set to api.

public function info() {
    return [
        'title'        => 'Stripe Gateway',
        'gateway_type' => 'api', // Required for API logic
        'currency'     => 'USD',
        'tab'          => 'global',
        'logo'         => 'assets/logo.jpg',
    ];
}

`process_payment($data)`

Triggered when the user initiates checkout. Use this to create a "Checkout Session" via cURL.

Redirecting: Use JavaScript location.href to send the user to the provider's URL.
Success URL: Use pp_callback_url() to generate the return path.

`callback($data)`

This is the "Return URL" where the user lands after payment.

Verification: You must re-verify the payment status using the session_id or token provided in the URL.
Finalization: Use pp_set_transaction_status() to update the database.

`ipn($data)`

Used for background notifications (Webhooks). It works similarly to callback() but is triggered by the provider's server, not the user's browser.

Helper Functions Reference

Your gateway class has access to these built-in system functions:

Function	Description
`pp_callback_url()`	Generates the URL the provider needs to redirect the user back to the `callback()` method.
`pp_checkout_address($ref)`	Generates the final "Payment Success" page for the user.
`pp_set_transaction_status()`	The most important function. It updates the invoice to `completed`, `pending`, or `failed`.

Implementation Standard (Code Snippet)

When marking a transaction as complete, follow this standard structure for pp_set_transaction_status:

PHP

$moreinfo = [
    [
        'label' => 'External Transaction ID',
        'value' => $provider_trx_id
    ],
    [
        'label' => 'Payment Method',
        'value' => 'Credit Card'
    ]
];

// Usage: pp_set_transaction_status(Reference, Status, GatewayID, ProviderTrxID, ExtraArray);
pp_set_transaction_status($data['transaction']['ref'], 'completed', $data['gateway']['gateway_id'], $provider_trx_id, $moreinfo);

Developer Checklist

Amount Conversion: Many APIs (like Stripe) expect amounts in cents. Multiply your amount by 100: (int) round($amount * 100).
Basic Auth: For APIs using Secret Keys, use curl_setopt($ch, CURLOPT_USERPWD, $key . ":");.
Security: Always compare the invoice_id returned by the API with $data['transaction']['ref'] to prevent cross-invoice payment fraud.