Inventory-Enabled Payment Confirmation Service

Overview

This document explains the payment processing flow integrated with an inventory check feature. The process ensures that payments are only completed if the requested items are available in stock. This feature is designed to prevent overselling and ensure a seamless customer experience.

---

Key Components

1. User: The customer initiating the payment.
2. PortOne Checkout: The frontend interface where the user interacts to make a payment.
3. PortOne Backend (PBE): The backend system that handles payment processing and communicates with the PSP and Merchant Backend.
4. PSP (Payment Service Provider): The external payment gateway that authorizes and captures payments.
5. Merchant Backend: The merchant's system controls inventory management and order processing.
6. Pending Page: A temporary page is displayed to the user while the payment and inventory check are processed.

---

Payment Flow with Inventory Check

Step-by-Step Process

1. User Initiates Payment
   • The user clicks "Pay Now" on the PortOne checkout.
2. Payment Initialization
   • Checkout sends a request to PBE to initialise the payment.
3. PSP Authorization
   • PortOne Backend communicates with the PSP to authorize the payment.
4. Pending Page Display
   • Once the PSP authorisation is successful, PBE directs the user to a pending page on checkout while the inventory check is performed.
5. Inventory Check Trigger
   • PBE triggers an inventory check by sending a request to the Merchant Backend.
6. Merchant Backend Processing
   • Sends a confirmation ("Ok") back to PBE if the inventory is available.
   • Response Handling:
     • Check the HTTP response status code.
       • If the status code is 200 OK, mark the confirmation as successful.
       • If the status code is not 200 OK, send the reason in JSON
   • Recommended
     The Merchant Backend processes the inventory check:
     - Verifies item availability.
     - Blocks the item stock to prevent overselling.
7. Payment Capture
   • PBE requests the PSP to capture the payment (complete the transaction).
8. Payment Result
   • PSP sends the capture result back to PBE.
9. User Redirection
   • PBE checks the payment result and redirects the user to the appropriate page (success or failure) on checkout.
10. Transaction Result Webhook
    • PBE sends a webhook to the Merchant Backend with the final transaction result.
    • Recommended
      The Merchant Backend updates the inventory:
      - Marks the item as sold if the payment is successful.
      - Unblocks the item stock if the payment fails.

---

Benefits for Merchants

• Prevents Overselling: Ensures that payments are only completed if the inventory is available.
• Real-Time Inventory Management: Automatically blocks and updates stock based on payment results.
• Seamless User Experience: Users are kept informed with a pending page while the system processes their payment and inventory check.
• Reduced Manual Intervention: Automates the inventory and payment reconciliation process.

---

Available PSPs

1. PayLetter Global

• Seamless Credit Card

---

Integration Requirements

To enable this feature, ensure the following:

1. Merchant Backend API:
   • Implement an endpoint to handle inventory checks and stock blocking.
   • Implement a webhook endpoint to receive transaction results from PBE.
2. Inventory Management System:
   • Ensure real-time inventory tracking and stock-blocking capabilities.
3. PortOne Dashboard Configuration:
   • Ensure the merchant's endpoint to handle inventory checks is configured in the PortOne Dashboard in Settings > Advanced page in the Inventory-Enabled Payment Confirmation Service section.
4. PSP Integration:
   • Ensure the PSP supports authorization and capture flows.

---

Merchant development

To support the inventory confirmation process, merchants are required to implement an endpoint in their backend system. PortOne's backend (PBE) will send requests to this endpoint from a specific IP address. The endpoint will receive a JSON payload containing the necessary transaction details. The merchant's backend must process this request and respond with an appropriate HTTP status code and a JSON response.

Endpoint Requirements

1. Endpoint Type:

   • HTTP Method: POST
   • Endpoint URL: Provided by the merchant and configured in the PortOne Dashboard in Settings > Advanced page in the Inventory-Enabled Payment Confirmation Service section (e.g., https://merchant-backend.com/inventory-confirmation).

2. Request Source IP:

   • PortOne will communicate with the merchant's endpoint using its designated IP address. To ensure secure communication, merchants should whitelist this IP. Please contact your PortOne business partner to obtain the specific IP address for whitelisting.

3. Request Payload:

   The endpoint will receive a JSON payload with the following structure:

   JSON

   {
     "portone_key": "merchant_key_123",
     "merchant_order_ref": "order_ref_456",
     "portone_order_ref": "portone_order_ref_789",
     "amount": 100.50,
     "currency": "USD"
   }
   

Parameter list

portone_key

string

The PortOne key of the merchant

---

merchant_order_ref

string

The merchant's order reference while creating the transaction.
This will be the merchant_order_ref used to create the payment link/checkout.

---

portone_order_ref

string

The unique order reference generated by PortOne.

---

amount

float64

The transaction amount.

---

currency

string

The currency of the transaction (e.g., USD).

---

4. Response Requirements:

   The merchant's backend must respond with the following:

   • HTTP Status Code:
     • 200 OK: Indicates that the inventory check was successful, and the item is available.
     • Any other status code (e.g., 400 Bad Request, 500 Internal Server Error): Indicates a failure in processing the inventory check.
   • Response Body:
     If the status code is not 200 OK, the response body must include a JSON object with a reason field explaining the failure. For example:
     JSON

     {
       "reason": "Insufficient inventory"
     }
     

     If the status code is 200 OK, the response body should be empty

5. Timeout Handling

   PortOne's backend (PBE) will wait for a response from the merchant's endpoint for a maximum of 10 seconds. If the merchant's endpoint does not respond within this time, the request will be considered timed out, and the payment will be rejected.

---

Example Scenarios

Successful Payment

1. The user pays for an item.
2. Inventory is available.
3. Payment is captured, and the item is marked as sold.

Failed Payment (Insufficient Inventory)

1. The user pays for an item.
2. Inventory is unavailable.
3. Payment is not captured, and the item stock is unblocked.

---

Testing and Validation

Merchants should thoroughly test the endpoint to ensure it:

1. Correctly processes valid requests.
2. Handles invalid or missing fields appropriately.
3. Responds with the correct status codes and messages for various scenarios (e.g., insufficient inventory, internal errors, timeouts).

---

By implementing this endpoint, merchants can seamlessly integrate with PortOne's payment processing flow, ensuring that payments are only completed when inventory is available. This enhances the customer experience and prevents overselling.