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:
- Generate
checksum
by creating hash ofpayload body
of these requests using HMAC algorithm and signed usingExtension API Secret
. Sample code. - 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:
- Generate
checksum
by creating hash of request body using HMAC algorithm and signed usingExtension API Secret
. Sample code. - Pass the checksum generated in step 1 in request body when calling updatePaymentSession and updateRefundSession API
- Fynd platform validates API request using this checksum.
Sample code for checksum generation of request payload
- Python
- Javascript
- Java
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)
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);
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:
- Generate
checksum
from payment transaction IDgid
parameter received in these API requests using HMAC algorithm and signed usingExtension API Secret
. Sample code. - 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
- Javascript
- Java
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)
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)
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:
- Generate
checksum
by encodingExtension API Secret
using base64 encoding. Sample code. - 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
- Javascript
- Java
import base64
secret = bytes("EXTENSION_API_SECRET", 'utf-8')
basic_auth = "Basic " + base64.b64encode(secret).decode('utf-8')
print(basic_auth)
const secret = "EXTENSION_API_SECRET";
const basic_auth = "Basic " + btoa(secret);
console.log(basic_auth);
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).