Skip to main content

Verify Payment and Complete Platform Checkout

The verify endpoint is responsible for processing payment responses from payment gateways, verifying payment authenticity, extracting user's addresses, completing platform checkout, and updating payment status. This endpoint is called by the frontend Payment Handler after a user completes payment in the payment gateway modal.

Connection to the flow: This endpoint receives payment data from the payment handler, which was triggered after the user completed payment in the modal that was opened using the configuration returned by your Buy Now Endpoint. After verification completes, the response is used by the payment handler to redirect users to the success page.

Implementation: The verification logic is implemented in your controllers. See the Payment Verification Function section for detailed implementation patterns and helper functions.

Verification Flow​

The verification endpoint follows this sequence:

  1. Signature Verification: Validates payment authenticity using cryptographic signatures
  2. Address Extraction: Retrieves shipping and billing addresses from payment gateway order details
  3. Anonymous cart (guest): If the order is anonymous (is_anonymous_cart), resolve a user_id before checkout (see Anonymous cart: user resolution below), then call platform checkout with that user_id and the x-anonymous-cart: true header.
  4. Platform Checkout: Completes checkout using platform's platformCheckoutCartV2 FDK method with extracted addresses (and with x-anonymous-cart: true when the order is anonymous).
  5. Clear anonymous cart: After successful checkout, if the order was anonymous, call the platform's delete-cart API for the order's cart_id with x-anonymous-cart: true (see Anonymous cart: clearing cart after checkout); log errors but do not fail the flow.
  6. Payment Update: Updates payment status in platform using FDK after successful checkout
  7. Response: Returns comprehensive verification results to the frontend

Signature Verification​

Signature verification is the first and most critical step in the verification process. It ensures that the payment response is authentic and hasn't been tampered with.

Implementation Details​

  • Signature Format: Payment gateways use specific formats for signature generation.
  • Credentials Source: Always retrieve credentials from the database using the application ID stored in order meta.
  • Verification Algorithm: Use HMAC SHA256 to generate the expected signature and compare it with the received signature
  • Logging: Log detailed verification information including signature strings, credential retrieval, and comparison results for debugging
// Example: Signature verification
const signatureString = `${gateway_order_id}|${payment_id}`;
const expectedSignature = crypto
  .createHmac('sha256', credentials.key_secret)
  .update(signatureString)
  .digest('hex');

const isAuthentic = expectedSignature === received_signature;

if (!isAuthentic) {
  return res.status(400).json({
    success: false,
    message: 'Payment signature verification failed'
  });
}

Address Extraction​

After successful signature verification (completed in the previous step), extract shipping and billing addresses from the payment gateway order details. These addresses are required to complete platform checkout in the next step. The addresses collected by the payment gateway during the modal interaction are stored in the gateway's order details and must be retrieved using the gateway's API.

Implementation Details​

  • Fetch Order Details: Call payment gateway API to retrieve complete order details using the gateway order ID
  • Address Mapping: Map payment gateway address format to platform address format with proper field mapping
// Example: Extract addresses from payment gateway order details
const gatewayOrderDetails = await fetchGatewayOrderDetails(
  gateway_order_id,
  credentials
);

const shippingAddress = gatewayOrderDetails.customer_details?.shipping_address;
const billingAddress = gatewayOrderDetails.customer_details?.billing_address || 
                      shippingAddress;

Platform Checkout​

After extracting addresses (and for anonymous cart, after resolving user_id), complete the platform checkout by calling the platformCheckoutCartV2 FDK method with the extracted addresses. This creates the platform order using the addresses collected by the payment gateway during the modal interaction. The platformCheckoutCartV2 FDK method uses the cart ID that was saved in the order meta during order creation. For guest user's orders, set user_id in the checkout payload (from user resolution) and include x-anonymous-cart: true in requestHeaders.

const checkoutHeaders = { 'x-ordering-source': 'storefront' };
if (order.meta?.is_anonymous_cart) {
  checkoutHeaders['x-anonymous-cart'] = 'true';
}
const response = await applicationClient.cart.platformCheckoutCartV2({
  id: cartId,
  body: checkoutPayload, // include user_id for anonymous checkout
  requestHeaders: checkoutHeaders
});

Anonymous cart​

User Resolution​

When the order is anonymous, you must have a user_id before calling platform checkout. First search for an existing user by phone (registered, not logged in); if found, use that user_id. If not found, create a new user with phone and name from checkout and use the new user_id.

Clearing Cart After Checkout​

After payment is confirmed and platform checkout has succeeded, clear the anonymous cart so it is not reused. Clear only when the order is anonymous, payment is confirmed, checkout succeeded, and you have a valid cart_id in order meta. Call the platform’s delete-cart API with that cart_id and x-anonymous-cart: true. Run this in both the payment verification handler (browser callback) and the webhook handler; treat failures as non-fatal (log and continue). See Controllers for the exact pattern.

Payment Update via FDK​

After successful platformCheckoutCartV2, update the payment status in the platform using payment API. This links the payment gateway payment to the platform's payment session.

// Example: Update payment via FDK
if (!isCodPayment && checkoutResult.success && merchantTransactionId) {
  const paymentVerification = await verifyFyndPayment(
    order,
    gatewayOrderDetails,
    checkoutResult,
    payment_id,
    gateway_order_id,
    req
  );
}

Response Structure​

The verification endpoint returns a comprehensive response that includes verification status, checkout results, and payment verification status. This response is received by your Payment Handler, which extracts the platform order ID and uses it for redirection to the success page.

Response Format​

{
  success: true,
  message: 'Payment verified successfully',
  data: {
    order_id: internal_order_id,
    payment_id: payment_id,
    status: 'verified',
    gateway_order_details: {
      id: gateway_order_id,
      status: gateway_order_status,
      has_customer_details: true
    },
    fynd_checkout: {
      order_id: fynd_order_id,
      merchant_transaction_id: merchant_transaction_id,
      success: true,
      message: 'Checkout completed'
    },
    fynd_payment_verification: {
      success: true,
      merchant_transaction_id: merchant_transaction_id,
      fynd_order_id: fynd_order_id
    }
  }
}

The verify endpoint completes the backend portion of the checkout flow. The frontend payment handler uses this response to complete the user journey.