Need to know

Pre-requisites

Before starting to build your payment extension, make sure you have registered your payment extension in your partner panel and obtained Extension API Key and Extension API Secret.

Verifying API calls

To keep the communication between Fynd platform and payment extension secure, Fynd Platform uses checksum generated using Extension API Secret to verify communications. Refer below guide to know how the payment API are verified.

Verifying Initiate Payment Transaction and Initiate Refund Transaction API

Follow below steps:

1. Generate checksum by creating hash of payload body of these requests using HMAC algorithm and signed using Extension API Secret. Sample code.
2. Compare the checksum generated in step 1 with the checksum header received in these API requests. Only if both checksum match, it should proceed with the request.

Passing checksum in updatePaymentSession and updateRefundSession API

Follow below steps:

1. Generate checksum by creating hash of request body using HMAC algorithm and signed using Extension API Secret. Sample code.
2. Pass the checksum generated in step 1 in request body when calling updatePaymentSession and updateRefundSession API
3. Fynd platform validates API request using this checksum.

Sample code for checksum generation of request payload

Python

import hmac
import hashlib
import json

payload = {} # python dictionary of request body
secret = "EXTENSION_API_SECRET" # EXTENSION_API_SECRET
message = json.dumps(payload, separators=(',', ':'))
hmac_obj = hmac.new(secret.encode('utf-8'), message.encode('utf-8'), hashlib.sha256)
checksum_auth = hmac_obj.hexdigest()
print(checksum_auth)

Javascript

const crypto = require("node:crypto");

request_payload = {}
const message = JSON.stringify(request_payload) // body of payload
const secret = "EXTENSION_API_SECRET"
let encodedBytes = Buffer.from(message, 'utf-8');
const hmac = crypto.createHmac('sha256', secret).update(encodedBytes);
const checksum_auth = hmac.digest('hex').toString();
console.log(checksum_auth);

Java

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.security.InvalidKeyException;
import java.security.NoSuchAlgorithmException;
import java.util.HashMap;
import java.util.Map;

public class HmacExample {
    public static void main(String[] args) {
        String secret = "EXTENSION_API_SECRET";
        Map<String, Object> payload = new HashMap<>();;

        // Add key-value pairs to payload if needed, e.g., payload.put("key", "value");

        try {
            Mac sha256_HMAC = Mac.getInstance("HmacSHA256");
            SecretKeySpec secret_key = new SecretKeySpec(secret.getBytes(), "HmacSHA256");
            sha256_HMAC.init(secret_key);

            String message = payload.toString();
            byte[] hmacData = sha256_HMAC.doFinal(message.getBytes());
            StringBuilder result = new StringBuilder();
            for (byte b : hmacData) {
                result.append(String.format("%02x", b));
            }
            String checksum_auth = result.toString();
            System.out.println(checksum_auth);
        } catch (NoSuchAlgorithmException | InvalidKeyException e) {
            e.printStackTrace();
        }
    }
}

---

Verifying Get Payment Status and Get Refund Status API

Follow below steps:

1. Generate checksum from payment transaction ID gid parameter received in these API requests using HMAC algorithm and signed using Extension API Secret. Sample code.
2. Compare the checksum generated in step 1 with the checksum header received in these API requests. Only if both checksum match, it should proceed with the request.

Sample code for checksum generation of transaction ID

Python

import hmac
import hashlib
import json

secret = "EXTENSION_API_SECRET" # EXTENSION_API_SECRET
message = "gid" # order gid
hmac_obj = hmac.new(secret.encode('utf-8'), message.encode('utf-8'), hashlib.sha256)
order_checksum_auth = hmac_obj.hexdigest()
print(order_checksum_auth)

Javascript

const crypto = require("node:crypto");

const message = "gid" // order gid
const secret = "EXTENSION_API_SECRET"
const hmac = crypto.createHmac('sha256', secret).update(message);
const checksum_auth = hmac.digest('hex').toString();
console.log(checksum_auth)

Java

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.security.InvalidKeyException;
import java.security.NoSuchAlgorithmException;
import java.util.HashMap;
import java.util.Map;

public class HmacExample {
    public static void main(String[] args) {
        String secret = "EXTENSION_API_SECRET";

        try {
            Mac sha256_HMAC = Mac.getInstance("HmacSHA256");
            SecretKeySpec secret_key = new SecretKeySpec(secret.getBytes(), "HmacSHA256");
            sha256_HMAC.init(secret_key);

            String message = "gid";
            byte[] hmacData = sha256_HMAC.doFinal(message.getBytes());
            StringBuilder result = new StringBuilder();
            for (byte b : hmacData) {
                result.append(String.format("%02x", b));
            }
            String checksum_auth = result.toString();
            System.out.println(checksum_auth);
        } catch (NoSuchAlgorithmException | InvalidKeyException e) {
            e.printStackTrace();
        }
    }
}

---

Verifying get activation status API

Follow below steps:

1. Generate checksum by encoding Extension API Secret using base64 encoding. Sample code.
2. Compare the checksum generated in step 1 with the authorization header received in this API request. Only if both checksum match, it should proceed with the request.

Sample code for checksum generation using base64 encoding of extension API secret

Python

import base64

secret = bytes("EXTENSION_API_SECRET", 'utf-8')
basic_auth = "Basic " + base64.b64encode(secret).decode('utf-8')
print(basic_auth)

Javascript

const secret = "EXTENSION_API_SECRET";
const basic_auth = "Basic " + btoa(secret);
console.log(basic_auth);

Java

import java.util.Base64;

public class BasicAuthEncoder {
    public static void main(String[] args) {
        // The secret key that needs to be encoded
        String secret = "EXTENSION_API_SECRET";
        
        // Encoding the secret using Base64
        String basicAuth = "Basic " + Base64.getEncoder().encodeToString(secret.getBytes());
        
        // Printing the encoded Basic Authentication string
        System.out.println(basicAuth);
    }
}

---

Idempotency

The payment extension must support idempotency to ensure consistent data and a seamless buyer experience. This can be done by using transaction ID gid which will be unique for each transactaion. For example if extension receives multiple payment (or refund) initiate calls from platform for same gid, then extension must only process first request and for subsequent requests it should return the order ID (or refund ID) generated in the first request only and not create new orders (or refunds).