DOCSEARCHbyAlgolia
Submit Docs

Notch Pay Developer Guide

website·Indexed 29 days ago

https://notchpay-developer-guide.vercel.app

Documentation for integrating Notch Pay financial solutions to send and receive payments across various currencies and countries. Includes API references for Payments, Transfers, and Customers, as well as guides on authentication, webhooks, and error handling.

Tokens
6.1K
Snippets
27
Records
51
Agent score
75%

What's inside Notch Pay

  1. Choose a Notch Pay integration method

    Notch Pay provides multiple ways to integrate payment processing into your application. Popular integration methods include:

    1. Inline payments
    2. SDKs and Plugins
    3. Direct integration via API

    Developers can use provided mock data for testing, and should refer to the error message glossary and best practices documentation to facilitate the build process.

  2. Understand Notch Pay API communication protocols

    The Notch Pay API follows a RESTful architecture. It uses standard HTTP methods (GET, POST, PUT, DELETE) for communication and returns all responses in JSON format. To interact with the API, requests must include a Content-Type: application/json header and be authenticated using valid API Keys.

  3. Obtain and manage Notch Pay API keys

    Notch Pay provides three types of API keys based on the environment and security requirements:

    1. Public Sandbox Key: Used exclusively for the test environment.
    2. Public Key: Used for public-facing scenarios, such as front-end JavaScript code.
    3. Private Key: Used for high-risk endpoints (e.g., transfer). This key must be kept confidential, stored only on servers (preferably as environment variables), and never committed to Git or exposed in front-end code.

    To retrieve keys: Log in to the Notch Pay dashboard, navigate to Settings > Developer Settings, and select API Keys.

  4. Initialize a Notch Pay payment via API

    To start a transaction, send a POST request to the Initialize Notch Pay Payment API endpoint.

    Key Constraints & Requirements:

    • Mandatory Fields: email and amount are required.
    • Currency Formatting: The amount must be consistent with the currency. For example, if using XAF, the value must not contain decimals.
    • Reference: It is recommended to use a unique transaction identifier from your own system as the reference.
    • Callback URL: You must specify a callback URL (either in the API request or on the dashboard); otherwise, users will not be redirected back to your site after payment.
    • Authentication: Requests require an Authorization header with your PUBLIC_KEY.
    $url = "https://api.notchpay.co/payments/initialize";

$fields = [
    'email' => "customer@email.com",
    'amount' => "1000",
    'currency' => "XAF",
    'description' => "Payment description", // optional
    'reference' => 'your_unique_reference' // optional but recommended
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $fields);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    "Authorization: PUBLIC_KEY",
    "Cache-Control: no-cache",
));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$result = curl_exec($ch);
echo $result;

  5. Process payments using the Notch Pay Redirect Method

    The Redirect Method allows you to gather payments by redirecting customers to a Notch Pay hosted payment page. The workflow consists of three main steps: collecting payment information, initializing the payment via API to get a redirect link, and verifying the transaction after the customer is redirected back to your site.

  6. Implement the End to End (e2e) payment flow

    The e2e charge flow is used when a personalized user interface and custom payment process are required. Unlike hosted options, e2e requires the developer to collect payment information and manage the UI. The process consists of three core stages:

    1. Initialize: Submit payment and customer details to the complete payment endpoint.
    2. Consent: Obtain the customer's authorization through their payment provider (e.g., bank, mobile money, or card issuer).
    3. Verify: Call the verify payment endpoint to confirm the payment was successful before delivering value to the customer.

  7. Verify a Notch Pay transaction after redirect

    After a successful transaction, Notch Pay redirects the user to your specified callback URL with parameters appended to the query string.

    Example Callback URL: http://your_website.com/afterpayment_callback.php?trxref=YOUR_REFERENCE&reference=NOTCHPAY_REFERENCE&status=PAYMENT_STATUS

    Verification Steps:

    1. Extract the reference (the Notch Pay transaction reference) from the URL parameters.
    2. Call the verify endpoint using this reference to confirm the transaction status.
    3. Crucial: Always verify the transaction via the API before delivering value to the customer; the mere arrival of the user at the callback URL does not prove payment success.

  8. Manage Notch Pay account environments

    Notch Pay provides two operational modes to separate development from production:

    • Test Mode: Used for integration testing. It does not involve real money but maintains most API functions, including webhooks and email notifications. Use test credentials in this mode.
    • Live Mode: Used for real transactions with actual money. Only switch to this mode after thorough testing.

    Users can switch between these modes using the toggle button in the account header, which automatically swaps the displayed API keys.

  9. Handle Notch Pay payment completion webhooks

    To automate order fulfillment, configure a webhook URL in your dashboard. Notch Pay will send a payment.complete webhook event to your server immediately upon the successful completion of a payment.

  10. Secure input and output forms

    Prevent cross-site scripting (XSS) and SQL injection attacks by implementing the following:

    • Perform server-side validation on all user and service inputs (in addition to client-side validation).
    • Restrict inputs to required characters and specific field lengths using a whitelist of acceptable characters.
    • Encode all output, including headers, cookies, query strings, form fields, and hidden fields.
    • Use parameterized SQL queries for all database interactions.
    • Validate all uploaded files thoroughly.

  11. Implement webhook best practices

    To prevent timeouts and ensure reliability, follow these guidelines:

    • Avoid long-running tasks: Do not perform heavy processing or network calls directly within the webhook endpoint. Return a 200 status immediately and delegate tasks to a job queue.
    • Ensure Idempotency: Design your event processing to be idempotent so that receiving the same webhook event multiple times does not cause erroneous outcomes for the customer.

  12. Implement secure authentication policies

    Enhance application security with these authentication standards:

    • Enforce a strong password policy (minimum 8 alphanumeric characters, including at least one uppercase letter and one special character).
    • Implement input validation during login to prevent exploits.
    • Protect against brute-force attacks using account lockouts and second-factor authentication (2FA).
    • Store database credentials securely in a secrets manager.