Skip to main content

Payment Gateway Extension Document

Overview​

Payment gateway extensions are extensions that integrate with the Fynd Platform, offering tailor-made payment processing services for businesses. Only authorised Partners can create payment gateway extensions on Fynd Partners. These extensions bring the following benefits to seller stores:

  • Introduce extra payment options.
  • Execute particular actions on payment methods.
  • Enhance payment security for buyers.
  • Automate payment services, like recurring payments.
  • Choose whether to collect funds during purchase or fulfilment. For further details, consult Payment Authorization.

Extension Development Approval​

To develop a payment extension, a developer must be approved by the Fynd Partners. The approval process involves submitting domain URLs, supported payment methods, countries, currencies, and other relevant details.

Currently, only selected partners are invited to build payment extensions on the Fynd Platform. Get in touch with our team at partner-support@fyndplatform.com to know more.

How do payment gateway extensions function?​

Hosted payment gateway extensions redirect customers to a Payment mode page enabling them to complete the payment using methods supported by the Payment gateway.

Prerequisites​

Ensure the following conditions are met before proceeding:

  • Your extension has been registered on Fynd Partners
  • Your extension satisfies the following prerequisites:
    • Fulfills feature prerequisites.
    • Meets technical prerequisites.
    • Complies with seller experience prerequisites.

For additional details, consult the requirements for third-party payment gateway extensions.

Failure to adhere to these prerequisites may result in Fynd Platform removing your extension from the public list of payment gateways, suspending your access to the payments ecosystem, terminating your participation in the payments ecosystem, or initiating any other necessary actions.

Feature Prerequisites​

Payment gateway extensions must encompass the subsequent features:

  • sellers should be able to carry out charging, refunding, and conducting trial transactions.
  • The extension follows the required rules for Strong Customer Authentication in places where credit card payments are processed. This might mean implementing 3D Secure authentication.

Technical Prerequisites​

Idempotency​

The payment extension must support idempotency to ensure consistent data and a seamless buyer experience. This involves handling retry requests from the Fynd Platform or payment gateway in case of network failures or non-200 responses.

Retry Policy​

In the event of a non-200 response or network failure, the extension must implement a retry policy for requests to the Fynd Platform.

HMAC Verification​

To ensure data integrity and security, the payload is hashed using SHA-256 algorithms and added as a signature in header requests. The extension is responsible for verifying the payload before initiating payments and also generating an HMAC signature to be sent to the Fynd Platform for verification during payment status updates.

FDK Versioning​

The payment extension must use the latest or stable version of the FDK for development.

GDPR Implementation​

The extension must implement GDPR webhooks to comply with the General Data Protection Regulation. This involves the following actions:

  • Providing customer/seller data when requested through webhooks
  • Deleting personal data when requested by customers/sellers
  • Deleting shop/business data when requested by customers/sellers

Review Process​

Before going live, the payment extension must undergo a review by the Fynd Platform Admin

Seller experience conditions​

  • Payments extensions should be operational 24/7, with a minimum uptime of 99.95% during any timeframe.
  • Partners must respond within 2 hours during outages or problems.
  • Support should be offered to all sellers using the payments app.

Payment Extension Lifecycle​

Step 1: Create Partner Organisation​

  • Click here to learn how to create a partner organisation.

Step 2: Payment Extension Approval​

  • Once you have registered your organization on Fynd Partners, send an email to partner-support@fyndplatform.com
  • Our team will get in touch with you to assess your eligibility to create a payment extension
  • After approval, you will be able to create payment extension using the Fynd Partners panel

Step 3: Create Payment Extension​

Follow the below method to create a payment extension in the partner panel:

  1. Go to Fynd Partners.

    QG1

    Figure 1: Fynd Partners Dashboard

  2. Click Extensions.

    QG1

    Figure 2: Clicking Extensions

  3. Click Create Extension.

    QG1

    Figure 3: Clicking Create Extension

  4. Create an Extension dialog box will appear. Select Start from scratch

    QG1

    Figure 4: Selecting Start from scratch

  5. Enter the required information in the Create Extension form

    QG1

    Figure 5: Extension Creation Form

  6. Extension type: Select Payment from the dropdown.

  7. Choose Distribution Method: Select either Public or Private depending on whether you want to make the extension available to all Fynd Platform companies or specific companies.

  8. Basic Details:

    1. Extension Name: Enter the name for the extension.
    2. Contact Email: Enter the email address via which Fynd can contact you in case of any urgent issue with your extension
    3. Logo: Upload the logo for the extension.
    4. Description: Briefly describe the functionality of your payment extension.

  9. Extension URL: Enter the URL where you have hosted your payment extension.

    QG1

    Figure 6: Extension URL Field

  10. Permission: Payment extension is automatically assigned required permissions. If you want to request additional permissions you can use the Request additional permissions toggle.

    QG1

    Figure 7: Permission Field

  11. Additional Details

    QG1

    Figure 8: Additional Details

    1. Payment Method: Choose the payment method your extension will offer to users from the available options. If you want to add a payment method that is not available in the list. drop an email to partner-support@fyndplatform.com with the request to add a payment method.
    2. API Version: Select the API version your extension will use to receive requests from the Fynd Platform.
    3. Country: Select the country(s) from the dropdown that are supported by your payment extension.
    4. Currency: Select the currency(s) from the dropdown which is supported by your payment extension.
    5. Partnership Mode: Determine the partnership mode to enable sellers to use Fynd accounts for accepting payments from customers.
    6. Transaction Fee: Select the suitable option
      1. Fixed: If a single transaction fee applies to all supported payment methods.
      2. Variable: If the transaction fee varies across supported payment methods.
    7. Checkout Type:
      1. Standard: Redirects users to an extension-hosted website to complete the payment process using alternative payment methods supported by the extension.
      2. Custom: Allows users to finalize the payment process on the seller's website.
    8. Auto Capture: Check this option if your extension supports the automatic capture of payment amounts.

  12. Click Create Extension/Save Changes.

Step 4: Test your Extension​

Test your extension in the development account before submitting it for approval:

QG1

Figure 9: Clicking Select Store

  1. On the Extension Overview page, click Select Store within the "Test Extension" section.
  2. Select a suitable development account for testing purposes.
  3. You will be redirected to the development account of the Fynd Platform. In this account, you can test your extension to ensure it functions correctly and meets all necessary requirements.

Step 5: Publish Your Extension​

To initiate the extension review and publication process, users need to follow these steps:

QG1

Figure 10: Manage Listing

Submitting the Extension for Review:

  1. Go to the Publish tab and fill the form that appears

    QG1

    Figure 11a: Submission Form

    QG1

    Figure 11b: Submission Form

  2. Support

    1. Email Address: Enter the email address that sellers can use to get support from you.
    2. Phone Number: Provide a phone number that sellers can use to get support from you.
    3. Website URL: If you have a customer support page hosted on a website, provide a link to that page
    4. FAQ URL: Specify the URL where sellers can access frequently asked questions (FAQs) about the extension.
    5. Privacy Policy URL: Include the URL to the page containing the privacy policy for the extension.

  3. Review

    1. Review Notification Email: Enter the email address where you wish to receive notifications and updates about the review process.
    2. Review Instructions: Provide test credentials that can be used by our review team to assess your payment extension. Add any additional comments or specific review-related instructions.

  4. Click Submit

note

Once submitted, the status of the extension will change to "Under Review"

Important: If necessary, users can edit the extension's registration details and resubmit it for review. This will initiate the review process again.

Step 6: In Review & Published/Approved​

  • Review Process: During the review process, the Fynd Platform team assesses the extension for compliance with security and performance standards.
  • Approval and Publication: If the extension successfully passes the review and is approved, its status changes to "Published."
  • Public Extensions: For public extensions, once published, the extension becomes available in the payment settings for sellers to configure and add to their stores.
  • Private Extensions: In the case of private extensions, after approval, you can specify the companies to which you want to add your payment extension using the Subscribers tab
  • Non-Approval or Modifications: If the extension is not approved or requires modifications, we will notify you via email regarding the necessary steps. Please ensure that you regularly check both your business email associated with your Partner account and the email address provided in your registration details.

Edit Payment Extension Details​

Partners can customise specific details of any published payment extension by editing the setup of the extension. Partners can rename it, update its logo, and modify the extension URL, ensuring seamless alignment with branding and meeting evolving business requirements.

QG1

Figure 13: Edit Extensions

Payment Extension States​

Payment Extension State depends upon whether it’s a Public or Private Extension

Public​

The Payment Extension lifecycle comprises three distinct phases, each defining the extension's availability, installation options, and visibility to sellers:

  1. Development: During this phase, API keys and secrets are generated. The extension is developed and tested within development accounts. After the development and testing phases, it's submitted for approval to the Fynd Platform team.
  2. Under Review: In this stage, the extension undergoes the necessary evaluations and checks by the Fynd Platform review team.
  3. Published: Once the extension passes the review stage, it advances to the published phase. At this point, the extension becomes accessible to all Fynd Platform sellers.
  4. Rejected: If the extension is rejected during the review stage, it moves to the Rejected state. You need to work on the changes suggested by the review team and submit the extension again for approval.

Private​

The Payment Extension lifecycle also consists of three phases:

  1. Development: In this initial phase, essential API keys and secrets are generated, and the extension is developed. After the development is complete, it's submitted for approval to the Fynd Platform team.
  2. Under Review: During this stage, the extension successfully passes the required evaluations and checks.
  3. Approved: Upon approval by the Fynd Platform team, you will be able to add your payment extension to the required Fynd Platform Companies
  4. Rejected: If the extension is rejected during the review stage, it moves to the Rejected state. You need to work on the changes suggested by the review team and submit the extension again for approval.

Supported Features of Payment Gateway Extensions:​

Payment gateway extensions provide the following capabilities:

  • Payment Methods
  • Payment Operations

Supported Payment Methods​

Sellers can utilize payment gateway extensions on the Fynd Platform to seamlessly guide customers to a payment gateway-hosted page for completing payments. This encompasses a range of payment methods, such as:

  • Wallets
  • Buy Now Pay Later
  • Cards
  • UPI
  • Bank Transfers / Online Banking

Supported Payment Operations​

The supported payment methods enable the following operations:

  • Charge: Partners can securely gather a buyer’s payment details and process payment for their order.
  • Refund: sellers can effortlessly initiate refunds from their Fynd Platform.
  • Authorize: sellers can place a temporary hold on funds for later processing.
  • Capture: sellers can charge the previously authorized amount.
  • Void: sellers can cancel a previously placed authorization.

Responsibilities of Payment Gateway Partners​

Payment processing is a crucial aspect of the workflow for our domestic clients. Our stores operate 24/7, serving buyers within the country and utilizing the local currency. We depend on our Payment Gateway Partners to establish a secure buying environment for our customers and to support sellers in managing settlements and payouts.

Ensuring Payment Security​

During a buyer’s purchase, payment gateway extensions have the following responsibilities:

  • Collecting buyer payment details securely while adhering to relevant laws, PCI requirements, and market regulations. This includes the secure storage of buyer data.
  • Processing payments based on Fynd Platform’s specified parameters.
  • Redirecting the buyer back to Fynd Platform.
  • Settling transactions within a five-day period.

Partners are accountable for risk and fraud management. In cases where an unusually high percentage of a seller's payments are fraudulent or high-risk (as determined by Fynd Platform ), Fynd Platform may take appropriate action. This action could involve:

  • Removing the payment gateway extension from the list of Fynd Platform's payment gateways
  • Restricting access to Fynd Platform’s payments ecosystem
  • Taking any other necessary action

Clear Pricing and Flexible Agreements​

  • Partners are required to provide transparent and easily understandable pricing for sellers.
  • Promotional or introductory rates cannot be initially low and later increased.
  • Partners cannot label any fee, expense, or cost as Fynd Platform fees in invoices to sellers.
  • Partners must allow sellers to terminate their agreements with a 7-day notice period without any penalties or consequences.

Sharing of Revenue​

All Partners need to have a signed revenue share agreement with Fynd Platform. This agreement must be signed and submitted before Fynd Platform can approve a payment gateway extension for processing actual payments. The revenue share is calculated based on the total payment volume (total GMV) processed by the payment gateway extension for all Fynd Platform sellers with the extension installed.

Revenue share is calculated monthly on the total payments volume from the first day to the last day of each month.

Fynd Platform doesn't invoice or collect revenue share until your Payment Gateway Apps exceed XXX INR in total transaction volume. Once this threshold is reached, Fynd Platform sends an invoice to the provided billing email along with payment details.

Prohibited Actions​

Payment gateway extensions are not allowed to perform the following actions:

  • Use any Fynd Platform APIs except the Payments Apps API and mandatory GDPR webhooks.
  • Store payment credentials for unauthorized purposes. Credentials can only be used for the original transaction or services approved by Fynd Platform.
  • Distribute, share, transfer, or sell unauthorized access to Fynd Platform’s Payments extension without explicit approval.
  • Create fake or fraudulent sellers, orders, or sales.
  • Process payment methods like Apple Pay, Google Pay, Shop Pay, PayPal, and Alipay. These providers have a direct connection with Fynd Platform for enhanced performance and checkout conversion.

Naming Guidelines​

To ensure simplicity for sellers when choosing additional payment methods, adhere to the following rules when naming your payment gateway extension:

  • The name of the extension cannot contain marketing text. For instance, names like “Provider No-1” or “”Use 20 Payment Methods” are not allowed. sellers only see the name of the extension after they've chosen the payment method they wish to add.
  • The name of the extension cannot be manipulated to gain a higher listing.
  • Make sure that the payment methods and locations you offer are accurate, as this information is used to present the extension to sellers. Names created solely for higher listing priority won't be permitted.

Payment Extension API Guide​

Authentication​

In the context of payment-related operations, a crucial security measure is implemented through authentication and checksum validation. These mechanisms ensure the integrity and authenticity of payment transactions. Let's delve into the process and its significance: (For enhanced security, all payment-related endpoints require checksum validation. This involves passing a checksum key in the request headers.)

Process Overview​

When interacting with payment-related endpoints, such as initiating payment sessions or refunds, the request headers must include a specific header key called "checksum." This checksum is a unique value derived from the request parameters and is used to validate the integrity of the data exchanged between the client and the server.

Importance of Checksum Validation​

The inclusion of checksum validation enhances security in payment-related interactions. By validating the checksum, both the client and server ensure that the data exchanged has not been tampered with during transit. This process mitigates the risk of data manipulation or unauthorized access, safeguarding the integrity of payment transactions.

In essence, the authentication and checksum validation process forms a vital layer of protection, contributing to the trustworthiness and reliability of payment operations.

Partner can use this boilerplate as a reference → https://github.com/gofynd/fdk-payment-extension-javascript to develop payments extension using javascript.

To enable seamless payment processing, the Payment Extension must implement the following sessions:

Payment Session API​

Parameters: GID (Mandatory): Global Identifier, such as an order ID or cart ID, is a required field. Amount (Optional): The payment amount. currency: The currency for the refund. app_id: The ID of the application initiating the refund. request_id (Mandatory): A distinct ID used to initiate a refund session, usually the shipment ID.

Payment Session Initiation (POST)​

  • Endpoint: /api/v1/payment_session/:gid
  • Method: POST
  • Function: Initiates a payment session with the payment gateway and provides a redirect URL to redirect to the Payment gateway options page.

Description:

In this section, we'll explain how to initiate a payment session using the POST method. This is a crucial step in the payment process.

Example Request:

curl --location 'https://<extension_name>.extensions.fynd.com/api/v1/payment_session/TR64D4E0D50D7B9210BC' \
--header 'authority: https://<extension_name>.extensions.fynd.com' \
--header 'Content-Type: application/json' \
--header 'checksum: <CHECKSUM>' \
--data '{
    "customer_name": "sandbox user",
    "customer_email": "test@example.com",
    "app_id": "64d24a8a911bf1c20ac3685c",
    "company_id": 1,
    "customer_contact": "9876543210",
    "gid": "TR64D4E0D50D7B9210BC",
    "pf_order_id": "FY64D4E0D50D7B9210BC",
    "g_user_id": "64d24abeac64940007744e73",
    "amount": 23000,
    "currency": "INR",
    "seller_locale": "en",
    "locale": "en",
    "mode": "test",
    "payment_methods": [
        {
            "code": "CHECKOUT",
            "name": "CHECKOUT",
            "sub_payment_mode": []
        }
    ],
    "success_url": "https://test-company-1.sandbox.fynd.engineering/cart/order-status?cart_id=16&order_id=FY64D4E0D50D28A5AFE2&success=true&status=complete&address_id=1",
    "cancel_url": "https://test-company-1.sandbox.fynd.engineering/cart/order-status?cart_id=16&order_id=FY64D4E0D50D28A5AFE2&success=false&address_id=1",
    "billing_address": {
        "id": "64d367fa8e4f485777e10546",
        "uid": 1,
        "area": "area",
        "city": "Mumbai",
        "name": "sandbox user",
        "email": "test@example.com",
        "phone": "9876543210",
        "state": "Maharashtra",
        "address": "address",
        "country": "India",
        "pincode": "400001",
        "user_id": "64d24abeac64940007744e73",
        "landmark": "landmark",
        "area_code": "400001",
        "address_type": "home",
        "country_code": "91",
        "geo_location": {
            "latitude": 18.9385352,
            "longitude": 72.836334
        },
        "area_code_slug": "pincode",
        "country_iso_code": "IND",
        "country_phone_code": "91",
        "delivery_address_id": 1,
        "g_address_id": "1"
    },
    "shipping_address": {
        "id": "64d367fa8e4f485777e10546",
        "uid": 1,
        "area": "area",
        "city": "Mumbai",
        "name": "sandbox user",
        "email": "test@example.com",
        "phone": "9876543210",
        "state": "Maharashtra",
        "address": "address",
        "country": "India",
        "pincode": "400001",
        "user_id": "64d24abeac64940007744e73",
        "landmark": "landmark",
        "area_code": "400001",
        "address_type": "home",
        "country_code": "91",
        "geo_location": {
            "latitude": 18.9385352,
            "longitude": 72.836334
        },
        "area_code_slug": "pincode",
        "country_iso_code": "IND",
        "country_phone_code": "91",
        "delivery_address_id": 1,
        "g_address_id": "1"
    },
    "kind": "sale",
    "initiated_at": 1691672790
}'

Response Example for 200, 403, 500, 404:

   json
   {
       "success": true,
       "_id": "64d4e2c08e560b135e179538",
       "redirect_url": "https://<extension_name>.extensions.fynd.com/api/v1/pgloader/64d4e2c08e560b135e179538"
   }

Upon successful validation of the checksum and request parameters, the extension server responds with a success flag and a unique ID for the initiated payment session. Additionally, a redirect URL is provided, leading to the payment gateway page.

Please note that this example involves initiating a payment session and responding with a redirect URL to the payment gateway page. Checksum validation ensures the security of this payment initiation process.

Payment Session Details (GET)​

  • Endpoint: /api/v1/payment_session/:gid
  • Method: GET
  • Function: Returns status and details of a payment.

Description:

This API enables Fynd platform to retrieve comprehensive information about a payment by utilizing the HTTP GET method. It serves as a valuable tool for checking the current status and accessing the intricate details of a previously initiated payment.

Here, we explain how the Fynd Platform retrieves information about a payment session using the GET method. This allows Fynd platform to check the status and details of a previously initiated payment.

Example Request:

To access the payment session details, Fynd platform can utilize a command-line tool like cURL or implement python or nodejs code to validate payment at extension side. The following example demonstrates how to make a GET request to retrieve payment session information:

   bash
   curl --location --request GET 'https://<extension_name>.extensions.fynd.com/api/v1/payment_session/TR64D4E0D50D7B9210BC' \`
   --header 'authority: https://<extension_name>.extensions.fynd.com'`

Response Example for 200, 401, 500:

{
    "gid": "TR659D293C0DA316738F",
    "status": "complete",
    "total_amount": 388,
    "currency": "INR",
    "payments": [
        {
            "payment_id": "2024010",
            "order_id": "fbcbc0be5",
            "captured": true,
            "status": "complete",
            "amount_captured": 38800,
            "amound_refunded": null,
            "gid": "TR659D293C0DA316738F",
            "g_user_id": "6541373ab3200a93b5e895ff",
            "amount": 388,
            "merchant_locale": "en",
            "locale": "en",
            "mode": "live",
            "payment_methods": [
                {
                    "code": "JIOPP",
                    "name": "JIOPP",
                    "sub_payment_mode": []
                }
            ],
            "success_url": "https://testbuild.hostx1.de/cart/order-status?success=true&status=complete&order_id=FY659D293C0DDF8C2781&aggregator_name=JioOnePay&cart_id=659d29210bffab010120aaca&delivery_address_id=6541375d69b334aaf07f26c5&billing_address_id=6541375d69b334aaf07f26c5",
            "cancel_url": "https://testbuild.hostx1.de/cart/order-status?success=false&status=failed&order_id=FY659D293C0DDF8C2781&aggregator_name=JioOnePay&cart_id=659d29210bffab010120aaca&delivery_address_id=6541375d69b334aaf07f26c5&billing_address_id=6541375d69b334aaf07f26c5",
            "billing_address": {
                "id": "6541375d69b334aaf07f26c5",
                "uid": 11418,
                "area": "jhgf",
                "city": "NOIDA",
                "name": "Name",
                "email": "name@gofynd.com",
                "phone": "8888888888",
                "state": "UTTAR PRADESH",
                "sector": "",
                "address": "gde",
                "country": "India",
                "pincode": "200001",
                "user_id": "6541373ab3200a93b5e895ff",
                "landmark": "efs",
                "area_code": "200001",
                "state_code": "",
                "address_type": "home",
                "country_code": "+91",
                "geo_location": {
                    "latitude": 29.5821195,
                    "longitude": 71.3266991
                },
                "area_code_slug": "pincode",
                "country_iso_code": "IN",
                "country_phone_code": "+91",
                "delivery_address_id": 11418,
                "g_address_id": "11418"
            },
            "shipping_address": {
                "id": "6541375d69b334aaf07f26c5",
                "uid": 11418,
                "area": "jhgf",
                "city": "NOIDA",
                "name": "User",
                "email": "name@gofynd.com",
                "phone": "8888888888",
                "state": "UTTAR PRADESH",
                "sector": "",
                "address": "gde",
                "country": "India",
                "pincode": "201301",
                "user_id": "6541373ab3200a93b5e895ff",
                "landmark": "efs",
                "area_code": "201301",
                "state_code": "",
                "address_type": "home",
                "country_code": "+91",
                "geo_location": {
                    "latitude": 28.5821195,
                    "longitude": 77.3266991
                },
                "area_code_slug": "pincode",
                "country_iso_code": "IN",
                "country_phone_code": "+91",
                "delivery_address_id": 11418,
                "g_address_id": "11418"
            },
            "kind": "sale",
            "initiated_at": 1704798524
        }
    ]
}

This provides a clear example of what the expected response might look like for a 302 status code, along with other possible status codes (detailed examples of what the response might look like for different scenarios).

In summary, the "Payment Session Details (GET)" API is a valuable tool for querying and retrieving detailed information about payment sessions. Depending on the circumstances and the accuracy of the provided parameters, the API returns an appropriate status code along with relevant data or error messages.

Rendering Payment Gateway Page (GET)​

  • Endpoint: /api/v1/pgloader/:id
  • Method: GET
  • Function: Renders the payment gateway page.

Description:

The "Rendering Payment Gateway Page" endpoint serves a critical role in facilitating online payment processing through Extension. When customers proceed to make payments for their purchases, they need a secure and reliable environment to enter their payment information and complete the transaction. This is where the payment gateway page comes into play.

How it Works:

To initiate the process of rendering the payment gateway page, Fynd Platform make a GET request to the specified endpoint which is returned in the payment session API response. This request acts as a gateway to access the payment page hosted by the payment gateway.

Example Request:

curl 'https://<extension_name>.extensions.fynd.com/api/v1/pgloader/64d4e42adc0f6f8ac920067f' \
  -H 'authority: https://<extension_name>.extensions.fynd.com'

This GET request is used to retrieve the payment gateway page, which is essential for processing payments securely.

Response - Status 307 (Redirect):

Upon making the above request, Fynd platform will receive a response with a status code 307, indicating a redirect. This redirect will guide to the payment page where the actual payment processing takes place. It's a crucial step in the payment flow to ensure the security of payment information and transactions.

The Purpose of Redirection:

The redirection process is a fundamental component of the payment flow, serving multiple crucial purposes:

  • Security: Redirection ensures the security of payment information. By guiding users to a dedicated payment gateway page, the transaction takes place in a controlled and encrypted environment, minimizing the risk of data breaches.
  • User Experience: Redirection is seamless and user-friendly. It allows customers to comfortably complete their payment without leaving the context of the transaction.
  • Payment Processing: The payment gateway page is equipped with the necessary tools and integrations to process payments efficiently. It communicates with financial institutions, verifies transactions, and provides confirmation to both customers and sellers.

Placeholder Usage:

When crafting a GET request, the Fynd platform replaces the placeholder ":id" in the endpoint URL with the actual identifier of the payment page you intend to render. This identifier ensures that you are directing users to the correct payment page associated with their transaction.

In summary, the "Rendering Payment Gateway Page" endpoint allows Extension to utilize payment gateway SDK or transaction API to initiate payment, the user can complete their payment securely on payment gateway page.

Payment Session Refund (POST):​

  • Endpoint: /api/v1/payment_session/:gid/refund
  • Method: POST
  • Function: Initiates a refund with the payment gateway and returns acknowledgement in the response.

Description:

The Refund Session API allows Fynd platform to initiate a refund with the payment gateway extension for a specific payment. It enables to initiate refunds for specific payment through the payment gateway. Refunds are a common aspect of e-commerce, and this API streamlines the process.

To initiate a refund, Fynd Platform need to craft a POST request to the specified endpoint. This request should include a JSON payload containing various parameters essential to the refund process. These parameters are critical in ensuring that the refund is carried out accurately and securely.

Below is a comprehensive overview of how to utilize this API effectively. The request should contain a JSON payload with specific parameters related to the refund process.

Example Request:

A JSON payload containing various parameters related to the payment session initiation is sent. This payload includes customer information, app details, payment amounts, and more.

curl --location 'https://<extension_name>.extensions.fynd.com/api/v1/payment_session/TR64D4E0D50D7B9210BC/refund' \
--header 'authority: https://<extension_name>.extensions.fynd.com' \
--header 'Content-Type: application/json' \
--header 'checksum: <CHECKSUM>' \
--data '{
    "gid": "TR64D4E4250DB0CBEF1D",
    "pf_order_id": "FY64D4E4250DB0CBEF1D",
    "request_id": "16916747740991418099",
    "app_id": "64d24a8a911bf1c20ac3685c",
    "amount": 23000,
    "currency": "INR",
    "status": "initiate",
    "journey_type": "CANCEL/RETURN"
}'
response example for 200, 403, 500, 404

Response - Status 202 (Accepted): Upon successful initiation of the refund request and validation of the checksum and request parameters, the server responds with a status of "Accepted." This indicates that the refund process has been initiated successfully.

Example Response:

{
    "gid": "TR64D4E4250DB0CBEF1D",
    "pf_order_id": "FY64D4E4250DB0CBEF1D",
    "journey_type": "CANCEL/RETURN",
    "pf_order_id": "FY64D4E4250DB0CBEF1D",
    "aggregator_payment_details": {
        "payment_id": "pay_jm6i4aeryyluxatmtaqj3sjq6e",
        "aggregator_order_id": "hpp_4Nv_2-fVl7IY",
        "aggregator_customer_id": "",
        "captured": true,
        "amount_captured": 23000,
        "amound_refunded": 23000,
        "gid": "TR64D4E4250DB0CBEF1D",
        "g_user_id": "64d24abeac64940007744e73",
        "amount": 23000,
        "currency": "INR",
        "seller_locale": "en",
        "locale": "en",
        "mode": "test",
        "payment_methods": [
            {
                "code": "CHECKOUT",
                "name": "CHECKOUT",
                "sub_payment_mode": []
            }
        ],
        "success_url": "https://test-company-1.sandbox.fynd.engineering/cart/order-status?cart_id=16&order_id=FY64D4E4250D6229AA99&success=true&status=complete&address_id=1",
        "cancel_url": "https://test-company-1.sandbox.fynd.engineering/cart/order-status?cart_id=16&order_id=FY64D4E4250D6229AA99&success=false&address_id=1",
        // Other details omitted for brevity
        "initiated_at": 1691673638
    },
    "aggregator_payment_refund_details": {
        "request_id": "16916747740991418099",
        "amount": 23000,
        "status": "refund_initiated",
        "currency": "INR",
        "refund_utr": "act_lkgkgdbzwoketluyejrbc7fose",
        "payment_id": "pay_jm6i4aeryyluxatmtaqj3sjq6e",
        "receipt_number": "act_lkgkgdbzwoketluyejrbc7fose",
        // Other details omitted for brevity
        "created": 1691674945000
    }
}

This response provides detailed information about the initiated refund, including payment and refund details.

Payment Session Refund Details (GET):

  • Endpoint: /api/v1/payment_session/:gid/refund/:request_id
  • Method: GET
  • Function: Returns status and details of a payment session refund.

Description:

This API endpoint is designed to retrieve comprehensive information about the status and details of a refund. It is specifically associated with a particular gid (Global Identifier) and request_id, allowing Fynd platform to query and obtain a comprehensive overview of the payment and refund status for a specific transaction.

This endpoint retrieves the status and details of a payment session refund associated with a specific gid and request_id. It allows Fynd platform to query the payment and refund status comprehensively.

Example Request:

To access the details of a payment session refund, Fynd platform can use the cURL command-line tool or a similar Python or Java code. The following example demonstrates how to make a GET request to retrieve payment session refund information:

curl --location --request GET 'https://<extension_name>.extensions.fynd.com/api/v1/payment_session/TR64D4E0D50D7B9210BC/refund/16916747740991418099' \
--header 'authority: https://<extension_name>.extensions.fynd.com'

Response - Status 200:

Upon successfully querying the details of a specific payment session refund, the server responds with a status code of 200. This signifies that the request was valid, and it provides an extensive payload containing detailed information about both the payment and the refund. The information includes but is not limited to:

  • The current status of the payment session.
  • The total amount involved in the transaction.
  • Currency used for the payment.
  • Payment details, including payment ID.
  • Refund details, if applicable, including refund status, amount, and refund UTR (Unique Transaction Reference).

Example Response:

{
    "gid": "TR64D4E4250DB0CBEF1D",
    "status": "initiated",
    "total_amount": 23000,
    "currency": "INR",
    "pf_order_id": "FY64D4E4250DB0CBEF1D",
    "payment_details": {
        "payment_id": "pay_wtt5r23mpebexcjsxzylyjhn7a",
        // Other payment details omitted for brevity
    },
    "refund_details": [
        {
            "request_id": "16100144824381402124",
            "amount": 23000,
            "currency": "INR",
            "status": "refund_done",
            "refund_utr": "act_4lan4lrf2bxexdbinmqoln4nda",
            // Other refund details omitted for brevity
        }
    ]
}

In this response, Fynd platform can find the status of the payment session and details of any associated refund transactions.

Both payment and refund statuses are updated in the Fynd Platform using the FDK methods updatePaymentSession and updateRefundSession, respectively. This ensures a seamless and accurate payment processing experience within the Fynd ecosystem.

APIs for Handling Credentials​

Authentication​

To ensure the security of credential endpoints, all of them require basic authentication. Fynd platform includes the "authorization" and "checksum" header in your request.

Retrieve seller Secrets for Payment Gateway​

  • Endpoint: /api/v1/secrets/:app_id
  • Method: GET
  • Function: This endpoint retrieves a dictionary of secret fields populated with seller secrets when available; otherwise, it returns null values for each field.

Description:

This API endpoint plays a vital role in retrieving previously stored seller secrets related to the payment gateway per seller according to the application ID passed in the request.

Depending on the availability of these secrets, the API either returns their actual values or provides null values for each field, ensuring that Fynd platform always get a structured response.

Example Request:

To retrieve these seller secrets, Fynd platform can make a GET request to the following endpoint: /api/v1/secrets/:app_id.

Ensure that Fynd platform request includes the appropriate headers, including 'Content-Type' set to 'application/json' and 'authorization' for authentication.

The :app_id parameter in the URL should be replaced with the actual application identifier for which Fynd platform want to retrieve the secrets.

curl --location --request GET 'https://<extension_name>.extensions.fynd.com/api/v1/secrets/:app_id' \
--header 'Content-Type: application/json' \
--header 'authorization: xxx'

Response Example 1: Credentials are Available (Status: 200 OK)

When seller secrets are available for the specified application, the server responds with a status code of 200, indicating success. The response body is a structured dictionary of secret fields populated with the actual seller secrets. These fields typically include 'slug' (identifier), 'name' (human-readable name), 'required' (indicating whether the credential is mandatory), 'display' (indicating whether the credential should be displayed), and 'value' (the actual secret value).

{
    "app_id": "123",
    "data": [
        {
            "slug": "api_key",
            "name": "API Key",
            "required": true,
            "display": true,
            "value": "xxxx"
        }
    ]
}

Response Example 2: Credentials are Not Available (Status: 200 OK)

In cases where no seller secrets are stored for the specified application, the API still responds with a status code of 200, indicating success. However, the response now includes the same structured dictionary of secret fields, but with 'value' set to null for each field.

{
    "app_id": "123",
    "data": [
        {
            "slug": "", # empty value
            "name": "",
            "required": true,
            "display": true,
            "value": null
        }
    ]
}

In summary, this API is crucial for securely managing and retrieving payment-related secrets, ensuring that payment processing remains smooth and secure within the Fynd platform. Whether secrets are available or not, the structured response allows for effective handling of payment credentials.

Credential Form​

The Credential Form is a crucial component that partners must facilitate for sellers. This form serves as a means of credential verification, and sellers are required to submit it after installing the extension to gain access to the payment extension functionality.

QG1

Figure 12: Credential Form

Request method for creating the credential form: GET

curl 'https://checkoutcom.extensions.fyndx1.de/company/1/application/000000000000000000000001' \
  -H 'authority: checkoutcom.extensions.fyndx1.de' \
  -H 'accept: text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.7' \
  -H 'accept-language: en-GB,en-US;q=0.9,en;q=0.8' \
  -H 'cookie: _ga=GA1.1.471971826.1650521049; _ga_GW4EBY8BQ0=GS1.1.1653387625.4.1.1653387640.0; _ga_0GX7SFJN3X=GS1.1.1653408994.12.0.1653408994.0; _fw_crm_v=2b0c03c8-bc0b-4802-8137-4b9931905bec; company_id=1; ext_session_1=s%3Aa9591f93-cdf6-464a-8b71-50d197e8805d.ER0E6V4Nhp0M%2Fv4xqqGFzEdRe37NTkfjV3vOAQ26%2FqQ' \
  -H 'dnt: 1' \
  -H 'if-modified-since: Tue, 28 Nov 2023 16:12:21 GMT' \
  -H 'sec-ch-ua: "Google Chrome";v="119", "Chromium";v="119", "Not?A_Brand";v="24"' \
  -H 'sec-ch-ua-mobile: ?0' \
  -H 'sec-ch-ua-platform: "macOS"' \
  -H 'sec-fetch-dest: iframe' \
  -H 'sec-fetch-mode: navigate' \
  -H 'sec-fetch-site: same-site' \
  -H 'sec-fetch-user: ?1' \
  -H 'sec-gpc: 1' \
  -H 'upgrade-insecure-requests: 1' \
  -H 'user-agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/119.0.0.0 Safari/537.36' \
  --compressed
  • A protected GET and POST method needs to be created.
  • The incoming request for POST will be verified against the protected CURL if the request is for the same company and application ID.
  • Developer whoever/ make sure API they have created from the extension must be protected from the outside world. [protected API]

Errors​

  • In case of errors, all extension APIs follow a standard response format:

    {
        "success": false,
        "title": httpErrorTitle[statusCode] || "Internal Server Error",
        "message": err.message,
    }

  • The "httpErrorTitle" corresponds to various HTTP status codes:

    {
        400: "Request Validation Failed",
        401: "Unauthorized",
        403: "Forbidden",
        404: "Not Found",
        405: "Method Not Allowed",
        500: "Internal Server Error",
        // Other error codes...
    }

Note: Always replace placeholders with actual values and data for accurate results. These APIs enable secure management and retrieval of seller secrets essential for integrating with the payment gateway.

Fynd Platform FDK Method: Update Payment and Refund Status​

Summary:

The Fynd Platform FDK method enables extension to update payment and refund status to the Fynd platform. This functionality streamlines the payment and refund processing and ensures seamless integration with the Fynd ecosystem.

Here's a detailed breakdown of the supported operations:

1. updatePaymentSession

  • Description: This method allows you to update the payment session status on the Fynd platform. A payment_session is initiated against a global identifier (gid) which identifies the entity payment is initiated. e.g. order_id, cart_id. This endpoint is to update the status of the said payment session. You can find more details in the official documentation.

  • Usage:

    Promise:

        javascript
         const promise = platformClient.application("<APPLICATION_ID>").payment.updatePaymentSession({`
             gid: value,
             body: value
         });

    Async/Await:

        javascript
         const data = await platformClient.application("<APPLICATION_ID>").payment.updatePaymentSession({`
             gid: value,
             body: value
         });

  • Body Example Payload:

    {
        "gid": "TR64D4E4250DB0CBEF1D",
        "pf_order_id": "FY64D4E4250DB0CBEF1D",
        "status": "initiated",
        "total_amount": 100,
        "currency": "INR",
        "payment_details": [
            {
                "payment_id": "pay_wtt5r23mpebexcjsxzylyjhn7a",
                "aggregator_order_id": "hpp_yR3qKzIagWl9",
                "aggregator_customer_id": "cust_123",
                "captured": false,
                "amount_captured": 100,
                "amount_refunded": 100,
                "gid": "TR64D4E4250DB0CBEF1D",
                "status": "complete",
                "g_user_id": "1832452",
                "amount": 100,
                "currency": "INR",
                "seller_locale": "en",
                "locale": "en",
                "mode": "test",
                "payment_methods": [
                    {
                        "code": "NB",
                        "name": "Net banking",
                        "sub_payment_mode": [
                            {
                                "code": "SBIN",
                                "name": "State Bank of India"
                            }
                        ]
                    }
                ],
                "success_url": "",
                "cancel_url": "",
                "billing_address": {
                    "country_phone_code": "91",
                    "country_iso_code": "IND",
                    "geo_location": {
                        "longitude": 73.9721802,
                        "latitude": 21.0643252
                    },
                    "google_map_point": {
                        "address": "WXC7+AJC, Mumbai, Maharashtra, 400093, India",
                        "sub_locality": "Andheri East"
                    },
                    "expire_at": "timestamp",
                    "phone": "9876543210",
                    "state": "Maharashtra",
                    "landmark": "Andheri East",
                    "name": "Shopsense",
                    "tags": [],
                    "address": "Ajit Nagar, Kondivita, Andheri East",
                    "area": "Andheri East",
                    "g_address_id": "507f191e810c19729de860ea",
                    "country": "India",
                    "city": "Mumbai",
                    "address_type": "office",
                    "area_code_slug": "400093",
                    "email": "care@fynd.com",
                    "area_code": "400093"
                },
                "shipping_address": {
                    "country_phone_code": "91",
                    "country_iso_code": "IND",
                    "geo_location": {
                        "longitude": 73.9721802,
                        "latitude": 21.0643252
                    },
                    "google_map_point": {
                        "address": "WXC7+AJC, Mumbai, Maharashtra, 400093, India",
                        "sub_locality": "Andheri East"
                    },
                    "expire_at": "timestamp",
                    "phone": "9876543210",
                    "state": "Maharashtra",
                    "landmark": "Andheri East",
                    "name": "Shopsense",
                    "tags": [],
                    "address": "Ajit Nagar, Kondivita, Andheri East",
                    "area": "Andheri East",
                    "g_address_id": "507f191e810c19729de860ea",
                    "country": "India",
                    "city": "Mumbai",
                    "address_type": "office",
                    "area_code_slug": "400093",
                    "email": "care@fynd.com",
                    "area_code": "400093"
                },
                "kind": "sale",
                "created": 9247387542
            }
        ],
        "order_details": {
            "gid": "TR64D4E4250DB0CBEF1D",
            "amount": 100,
            "currency": "INR",
            "aggergator_order_details": {
                "aggregator_order_id": "hpp_yR3qKzIagWl9",
                "amount": 100,
                "currency": "INR",
                "aggregator": "checkoutcom",
                "status": "complete"
            }
        }
    }

    • Response Example: Status 200 (Success)

          json
           {
               "gid": "TR64D4E4250DB0CBEF1D",
               "status": "initiated",
               "total_amount": 100,
               "currency": "INR",
              "pf_order_id": "FY64D4E4250DB0CBEF1D",
               "platform_transaction_details": [
                   {
                       "object": "platform_payment",
                       "transaction_id": "pay_wtt5r23mpebexcjsxzylyjhn7a",
                       "payment_id": "pay_wtt5r23mpebexcjsxzylyjhn7a"
                   }
               ]
           }

    • Response Example: Status 4xx/5xx (Error)

          json
          {
              "success": false,
              "data": { "status": "failed" },
              "message": "error message"
           }

2. updateRefundSession

  • Description: This method enables the extension to update the refund session status on the Fynd platform. A refund_session is initiated against a refund request, and this endpoint is to update the status against the refund request_id. A gid is a unique identifier of the entity against which payment was received e.g. an order. Refer to the official documentation for more details.

  • Usage:

    Promise:

    javascript
    const promise = platformClient.application("<APPLICATION_ID>").payment.updateRefundSession({
    gid: value,
    requestId: value,
    body: value
    });

    Async/Await:

        javascript
            const data = await platformClient.application("<APPLICATION_ID>").payment.updateRefundSession({
                gid: value,
                requestId: value,
                body: value
            });

  • Example Payload:

    {
        "gid": "TR64D4E4250DB0CBEF1D",
        "pf_order_id": "FY64D4E4250DB0CBEF1D",
        "status": "initiated",
        "total_amount": 100,
        "currency": "INR",
        "refund_details": [
            {
                "request_id": "16100144824381402124",
                "amount": 100,
                "currency": "INR",
                "status": "refund_done",
                "refund_utr": "act_4lan4lrf2bxexdbinmqoln4nda",
                "payment_id": "pay_wtt5r23mpebexcjsxzylyjhn7a",
                "reason": "",
                "receipt_number": "act_4lan4lrf2bxexdbinmqoln4nda",
                "transfer_reversal": "",
                "source_transfer_reversal": "",
                "created": "",
                "balance_transaction": ""
            }
        ],
        "payment_details": {
            "payment_id": "pay_wtt5r23mpebexcjsxzylyjhn7a",
            "aggregator_order_id": "hpp_yR3qKzIagWl9",
            "aggregator_customer_id": "cust_123",
            "captured": false,
            "amount_captured": ,
            "status": "refund_done",
            "amount_refunded": 100,
            "gid": "TR64D4E4250DB0CBEF1D",
            "g_user_id": "1832442",
            "amount": 100,
            "currency": "INR",
            "seller_locale": "en",
            "locale": "en",
            "mode": "test",
            "payment_methods": [
                {
                    "code": "NB",
                    "name": "Net banking",
                    "sub_payment_mode": [
                        {
                            "code": "SBIN",
                            "name": "State Bank of India"
                        }
                    ]
                }
            ],
            "success_url": "",
            "cancel_url": "",
            "billing_address": {
                "country_phone_code": "91",
                "country_iso_code": "IND",
                "geo_location": {
                    "longitude": 73.9721802,
                    "latitude": 21.0643252
                },
                "google_map_point": {
                    "address": "WXC7+AJC, Mumbai, Maharashtra, 400093, India",
                    "sub_locality": "Andheri East"
                },
                "expire_at": "timestamp",
                "phone": "9876543210",
                "state": "Maharashtra",
                "landmark": "Andheri East",
                "name": "Shopsense",
                "tags": [],
                "address": "Ajit Nagar, Kondivita, Andheri East",
                "area": "Andheri East",
                "g_address_id": "507f191e810c19729de860ea",
                "country": "India",
                "city": "Mumbai",
                "address_type": "office",
                "area_code_slug": "400093",
                "email": "care@fynd.com",
                "area_code": "400093"
            },
            "shipping_address": {
                "country_phone_code": "91",
                "country_iso_code": "IND",
                "geo_location": {
                    "longitude": 73.9721802,
                    "latitude": 21.0643252
                },
                "google_map_point": {
                    "address": "WXC7+AJC, Mumbai, Maharashtra, 400093, India",
                    "sub_locality": "Andheri East"
                },
                "expire_at": "timestamp",
                "phone": "9876543210",
                "state": "Maharashtra",
                "landmark": "Andheri East",
                "name": "Shopsense",
                "tags": [],
                "address": "Ajit Nagar, Kondivita, Andheri East",
                "area": "Andheri East",
                "g_address_id": "507f191e810c19729de860ea",
                "country": "India",
                "city": "Mumbai",
                "address_type": "office",
                "area_code_slug": "400093",
                "email": "care@fynd.com",
                "area_code": "400093"
            },
            "kind": "sale",
            "created": "Date"
        }
    }

  • Response Example: Status 200 (Success)

     json
     {
         "gid": "TR64D4E4250DB0CBEF1D",
         "status": "initiated",
        "pf_order_id": "FY64D4E4250DB0CBEF1D",
         "total_refund_amount": 100,
         "currency": "INR",
         "platform_refund_details": [
             {
                 "transaction_id": "pay_wtt5r23mpebexcjsxzylyjhn7a",
                 "refund_id": "act_4lan4lrf2bxexdbinmqoln4nda"
             }
         ]
     }

  • Response Example: Status 4xx/5xx (Error)
     json
     {
         "success": false,
         "data": { "status": "failed" },
         "message": "error message"
     }

These Fynd Platform FDK methods are essential for keeping payment and refund statuses synchronized with the Fynd platform, ensuring a smooth and accurate payment processing experience within your extension.