DOCSEARCHbyAlgolia
Submit Docs

Pledg Integration Documentation

website·Indexed 34 days ago

https://docs.pledg.co/

Developer documentation for integrating Pledg's payment solution. Includes guides on API authentication, purchase management, payment schedule simulation, and various integration modes such as CMS modules (Magento v2), plugins, redirections, and purchase links. Covers technical principles including IPN notifications, environment settings (staging and production), and refund processes.

Tokens
15.7K
Snippets
54
Records
106
Agent score
56%

What's inside Pledg

  1. Overview of Pledg payment types

    Pledg provides merchants with two primary payment types to offer customers:

    1. Installment: The payment is split into several installments.
    2. Deferred: The payment is completed only after a specific delay.

  2. Configure PledgBySofinco widgets in WooCommerce

    Manage the visibility of Pledg informational widgets by navigating to Settings > PledgBySofinco. Available options include:

    • Enable product widget: Displays a widget on the product page to inform buyers about the solution.
    • Enable cart widget: Displays a widget on the cart page.
    • Automatic selection: Automatically selects a PledgBySofinco payment method at checkout if the buyer previously interacted with a widget.

  3. Handle payment error notifications

    To be notified of errors occurring after the payment screen, provide the optional errorNotificationUrl parameter during purchase creation. Pledg sends a POST request with a JSON body when the purchase state transitions to specific error or abandonment statuses.

    Key Behaviors:

    • Terminal States: Most error notifications (e.g., SCORING_KO, ABORTED, *_CANCELLED) are terminal, meaning the purchase is permanently closed.
    • Non-Terminal States: PRIMARY_KO and IDENTIFICATION_KO trigger notifications but keep the checkout session active, allowing the customer to potentially recover the flow.
    • Rejection Details: If acceptance_state is REJECTED, the acceptance_rejection_type and acceptance_rejection_subtypes fields will contain details. If acceptance_state is ABANDONED, these fields remain empty.
    {
   "reference" : "purchase_reference",
   "state" : "REVENUE_KO",
   "acceptance_state": "REJECTED",
   "acceptance_rejection_type": "NOT_ELIGIBLE",
   "acceptance_rejection_subtypes": ["Insufficient revenue"],
   "uid" : "pur_6c48d42b-f29b-4f84-bee8-3cb2b964b600",
   "loan_short_id": "1UW7Z0F5D21"
}

  4. Test the PledgBySofinco integration

    To verify the installation and configuration is working correctly:

    1. Add items to the shopping basket.
    2. Proceed to the payment step and select a PledgBySofinco method.
    3. Complete the transaction.
    4. Verify that the test order appears correctly in the administration "Orders" interface.

  5. Process refunds using Back mode

    For payments using virtual cards, no API is required to process a refund. Refund operations must be initiated directly in the merchant's PSP (Payment Service Provider) back office. Refunding the virtual card used for the payment will propagate the refund to the initial buyer.

  6. Receive notifications for successful purchases

    To receive a notification when a purchase is successfully completed, provide the optional paymentNotificationUrl parameter when creating the purchase. Pledg will send a POST request with a JSON body to this URL. The specific fields in the JSON body vary depending on the payment mode used (e.g., back mode or transfer mode).

  7. Manage settlement and monitoring in Transfer mode

    In Transfer mode, wire transfers are routed via Pledg's back office based on the merchant's IBAN. Settlement and operation monitoring can be handled in two ways:

    1. Manually: Using the dashboard to access lists of Orders and Transfers, with support for filters and exports.
    2. Automated: By retrieving and analyzing settlement files shared daily in a designated SFTP area.

  8. Handle customer refunds based on virtual card status

    Depending on whether a virtual card has been debited, refunds are handled differently:

    1. If the virtual card has already been debited: The merchant must recredit the virtual card. Pledg will be notified of this recredit approximately 2 days later and will then refund the customer.
    2. If the virtual card has not been debited: No action is required from the merchant. Pledg will be notified approximately 10 days later that the card was not debited and will automatically refund the customer.

  9. Secure settings using JWT signatures

    To prevent tampering, settings must be transmitted as a JSON Web Token (JWT) signature. The token is generated on the merchant's backend using a shared secret key.

    Payload Requirements: The JWT payload must contain all settings except:

    • The signature parameter itself
    • Callbacks (for plugin integrations)
    • The containerElement parameter (for plugin integrations)

    Workflow:

    1. Frontend sends request data to the merchant backend.
    2. Backend signs the data using the shared secret and returns the JWT.
    3. Frontend sets this JWT in the signature field when calling Pledg.
    const jwt = require('jsonwebtoken');

function generateSignature(data) {
    // The secret key to sign the JWT (Store in private area/env var)
    const secret = process.env.SECRET;

    // Generate the signature
    const signature = jwt.sign(
        { data: data },       // signed data
        secret,              // Secret Key
        { expiresIn: '1d' } // Options: signature expires in 1 day
    );

    return signature;
}

// Use case
const settings = {
    merchantUid: 'mer_efjhik1234567', 
    amountCents: 10000, 
    email: 'toto@dev.fr', 
    title: 'My Order', 
    reference: 'abcd', 
    phoneNumber: '0664667788'
};
const signature = generateSignature(settings);
console.log('generated signature:', signature);

  10. Configure Pledg Notification (IPN) infrastructure

    Pledg uses a classical Instant Payment Notification (IPN) mechanism to notify merchant backends of payment events. To ensure successful delivery of these webhooks, merchants must adhere to the following requirements:

    1. IP Whitelisting: Notifications are sent from two fixed IP addresses. These must be whitelisted in the merchant's infrastructure.
    2. User Agent: Requests use python-requests as the User Agent; this may need to be authorized in the merchant's firewall or security settings.
    3. Secure Protocol: Only https (secure) URLs are supported; http URLs will not be used.

  11. Test the Pledg integration in the Staging environment

    The staging environment is a sandbox where certain platform behaviors are mocked. Note the following constraints and requirements during testing:

    Behavioral Differences:

    • Purchase links are sent via email only (SMS is disabled).
    • OTP (One Time Password) phone verification is disabled.
    • There are no controls on purchase amounts, order counts per buyer, or country restrictions.

    Testing Requirements:

    • Use realistic test data (avoid keywords like 'test' or 'example').
    • Use a valid email address (e.g., via yopmail.com).
    • A valid phone number is required for Contract Signatures to receive validation codes.
    • For ID checks and Open Banking, contact the integration team for specimen IDs and guidance.

  12. Handle Ogone notifications in Back mode

    For Ogone integrations in Back mode, Pledg handles notifications similarly to the Payzen SOAP webservice: because the payment is completed server-to-server, Pledg sends the notification that the PSP would have normally sent to the merchant.