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 customer 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 popup.

Connection to the flow: This endpoint receives payment data from the payment handler, which was triggered after the user completed payment in the popup 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. Platform Checkout: Completes checkout using platform's checkoutCart mutation with extracted addresses
  4. Payment Update: Updates payment status in platform using FDK after successful checkout
  5. 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. Common format is order_id + "|" + payment_id (e.g., razorpay_order_id + "|" + razorpay_payment_id)
  • Credentials Source: Always retrieve credentials from the database using the application ID stored in order meta. Never hardcode credentials.
  • 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 popup 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 Location: Addresses are typically stored in customer_details.shipping_address and customer_details.billing_address
  • 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, complete the platform checkout by calling the checkoutCart GraphQL mutation with the extracted addresses. This creates the platform order using the addresses collected by the payment gateway during the popup interaction. The checkoutCart mutation uses the cart ID that was saved in the order meta during order creation.

Implementation Details​

  • Function Call: Use a dedicated function (e.g., callFyndCheckoutCart()) that handles address mapping and checkout
  • Address Mapping: Map payment gateway addresses to platform format before calling checkout
  • GraphQL Mutation: Call Fynd GraphQL checkoutCart mutation with delivery and billing addresses
  • Response Data: Extract merchant_transaction_id and fynd_order_id from the checkout response
// Example: Complete platform checkout
const checkoutResult = await callFyndCheckoutCart(
  order,
  gatewayOrderDetails,
  req,
  buyNow,
  isCodPayment
);

const merchantTransactionId = checkoutResult?.checkoutCart?.data?.merchant_transaction_id;
const fyndOrderId = checkoutResult?.checkoutCart?.order_id;

Payment Update via FDK​

After successful checkoutCart (completed in the previous step), update the payment status in the platform using FDK's payment API. This links the payment gateway payment to the platform's payment session. The merchant_transaction_id returned by checkoutCart is used here to update the payment session. This step must be completed before returning the verification response to the frontend.

Implementation Details​

  • Timing: Call payment update only after successful checkoutCart and when merchant_transaction_id is available
  • Function Call: Use a dedicated function (e.g., verifyFyndPayment()) that handles FDK payment update
  • FDK Method: Use applicationClient.payment.updatePaymentSession() to update the payment session
  • Checksum Secret: Use the correct checksum secret from extension configuration for payment updates
  • Skip for COD: Skip payment update for COD payments as they are handled automatically by the platform
// 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
    }
  }
}

Response Fields​

  • success: Boolean indicating overall verification success
  • data.gateway_order_details: Summary of payment gateway order details
  • data.fynd_checkout: Results from checkoutCart mutation including order_id and merchant_transaction_id
  • data.fynd_payment_verification: Results from FDK payment update including verification status
note

The response structure uses fynd_checkout and fynd_payment_verification to match platform naming conventions. Some implementations may use platform_checkout and payment_verification - always check both when extracting data from the response.

Error Handling​

Handle errors gracefully at each step:

  • Signature Verification Failure: Return 400 status with clear error message
  • Order Not Found: Return 404 status when order cannot be located
  • Address Extraction Failure: Log error but continue with response (payment is still verified)
  • Checkout Failure: Log error but return verification success (payment was verified)
  • Payment Update Failure: Log error but don't block response (checkout was successful)

Best Practices​

  1. Always verify signature first before processing any payment data
  2. Update transaction status immediately after successful signature verification
  3. Extract addresses from payment gateway rather than relying on frontend data
  4. Complete checkout before payment update to ensure order exists in platform
  5. Skip payment update for COD as platform handles COD automatically
  6. Log all operations for debugging and audit trails
  7. Return comprehensive responses with all relevant data for frontend processing

Next Steps​

After implementing the verify endpoint:

  1. Complete the flow: The verification response is used by your Payment Handler to determine success or failure
  2. Implement Redirection: Use the platform order ID from the verification response to redirect users to the success page
  3. Review Implementation: The verification logic uses helper functions documented in the Controllers page

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


Was this section helpful?