Get Public Key

GET

api

payment

key

Get Public Key

curl --request GET \
  --url https://cc.firmly.work/api/v1/payment/key \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://cc.firmly.work/api/v1/payment/key', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://cc.firmly.work/api/v1/payment/key",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://cc.firmly.work/api/v1/payment/key"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://cc.firmly.work/api/v1/payment/key")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "x-firmly-kid": "<string>",
  "kid": "<string>",
  "kty": "<string>",
  "n": "<string>",
  "e": "<string>",
  "use": "<string>"
}

Overview

This endpoint retrieves the current public key used for encrypting credit card data before sending it to Firmly’s payment endpoints. The key supports multiple formats to accommodate different encryption libraries and platforms.

The public key is rotated periodically for security. Always fetch the current key before encrypting payment data rather than caching it for extended periods.

Authentication

This endpoint requires no authentication and is publicly accessible.

Query Parameters

string

default:"JWK"

The format of the public key to returnSupported formats:

JWK - JSON Web Key format (default)
PEM - Privacy Enhanced Mail format
RSA - PEM using RSAPublicKey format

Response Headers

string

The key identifier (kid) - present for all formats

Response Formats

JWK Format (Default)

Returns a JSON Web Key with the following properties:

string

Key identifier/version

string

Key type (always “RSA”)

string

RSA modulus component (Base64URL encoded)

string

RSA exponent component (Base64URL encoded)

string

Key usage (always “enc” for encryption)

PEM Format

Returns the public key in PEM format as plain text:

Content-Type: text/plain
Key ID available in x-firmly-kid header
Standard PEM header/footer with base64 encoded key

RSA Format

Returns the public key in RSA-specific PEM format:

Content-Type: text/plain
Key ID available in x-firmly-kid header
Uses RSA PUBLIC KEY header/footer

Code Examples

// Fetch public key in JWK format (default)
async function getPublicKey() {
  const response = await fetch('https://cc.firmly.work/api/v1/payment/key');
  if (!response.ok) {
    throw new Error(`Failed to fetch public key: ${response.statusText}`);
  }
  
  const publicKey = await response.json();
  console.log('Key ID:', publicKey.kid);
  console.log('Key Type:', publicKey.kty);
  
  return publicKey;
}

// Use with Web Crypto API
async function importKey(jwk) {
  return await crypto.subtle.importKey(
    'jwk',
    jwk,
    {
      name: 'RSA-OAEP',
      hash: 'SHA-256'
    },
    false,
    ['encrypt']
  );
}

import requests

def get_public_key_pem():
    """Fetch public key in PEM format"""
    response = requests.get(
        'https://cc.firmly.work/api/v1/payment/key',
        params={'format': 'PEM'}
    )
    
    if response.status_code != 200:
        raise Exception(f"Failed to fetch public key: {response.status_code}")
    
    # Get key ID from header
    key_id = response.headers.get('x-firmly-kid')
    public_key_pem = response.text
    
    print(f"Key ID: {key_id}")
    return public_key_pem, key_id

# Use with cryptography library
from cryptography.hazmat.primitives import serialization
from cryptography.hazmat.backends import default_backend

def load_public_key(pem_data):
    return serialization.load_pem_public_key(
        pem_data.encode('utf-8'),
        backend=default_backend()
    )

# Get JWK format (default)
curl https://cc.firmly.work/api/v1/payment/key

# Get PEM format
curl https://cc.firmly.work/api/v1/payment/key?format=PEM

# Get RSA format
curl https://cc.firmly.work/api/v1/payment/key?format=RSA

# Get PEM format and extract key ID from header
curl -i https://cc.firmly.work/api/v1/payment/key?format=PEM | grep x-firmly-kid

<?php
// Fetch public key in JWK format
function getPublicKey() {
    $url = 'https://cc.firmly.work/api/v1/payment/key';
    
    $response = file_get_contents($url);
    if ($response === false) {
        throw new Exception('Failed to fetch public key');
    }
    
    $publicKey = json_decode($response, true);
    
    echo "Key ID: " . $publicKey['kid'] . "\n";
    echo "Key Type: " . $publicKey['kty'] . "\n";
    
    return $publicKey;
}

// Fetch PEM format with headers
function getPublicKeyPEM() {
    $context = stream_context_create([
        'http' => ['method' => 'GET']
    ]);
    
    $url = 'https://cc.firmly.work/api/v1/payment/key?format=PEM';
    $response = file_get_contents($url, false, $context);
    
    // Extract key ID from headers
    foreach ($http_response_header as $header) {
        if (stripos($header, 'x-firmly-kid:') === 0) {
            $keyId = trim(substr($header, 13));
            break;
        }
    }
    
    return ['pem' => $response, 'kid' => $keyId];
}
?>

Response Examples

JWK Format Response

{
  "kid": "a81b2d581f2a42c09143eb6fdb918fff",
  "kty": "RSA",
  "n": "yURqBPP1k_kwMp8AiHeZya7zgO9ZulKrNvFYcQK2eIvkbl7VlhxYt6bnJ0urrUrJbuM_bbRg3yiwXtAN_BsHWTm6JwWSjRx3PQMIm0Yb-HGj2YM6moJ9YFACqtZB2zjkE98Q_TOhfAnYuoSIPsY3k9U1iJmi6gpaZ7E01QFGoRlAwB55yMETl3UT7uodGLRPBz_JGhRuDCJ1dVEfzcojUxOt7FFbRIGDGQzMTvmskRID3N50z6UwJOFwmP6N17qIMYCbr3IQg0fU75HsL-lChpA8m-EnvK0hL4CcNnBVqupxzhsKq2SSLigNBFC6J4gs3mV7L7qu1Q8u_Cg5tGVZiQ",
  "e": "AQAB",
  "use": "enc"
}

PEM Format Response

RSA Format Response

Usage with Encryption Libraries

JavaScript (Web Crypto API)

async function encryptWithJWK(data, jwk) {
  // Import the JWK
  const publicKey = await crypto.subtle.importKey(
    'jwk',
    jwk,
    {
      name: 'RSA-OAEP',
      hash: 'SHA-256'
    },
    false,
    ['encrypt']
  );
  
  // Encrypt the data
  const encrypted = await crypto.subtle.encrypt(
    { name: 'RSA-OAEP' },
    publicKey,
    new TextEncoder().encode(data)
  );
  
  // Convert to base64
  return btoa(String.fromCharCode(...new Uint8Array(encrypted)));
}

Python (cryptography)

from cryptography.hazmat.primitives import hashes
from cryptography.hazmat.primitives.asymmetric import padding
from cryptography.hazmat.primitives import serialization
import base64

def encrypt_with_pem(data, pem_key):
    # Load the PEM key
    public_key = serialization.load_pem_public_key(
        pem_key.encode('utf-8')
    )
    
    # Encrypt the data
    encrypted = public_key.encrypt(
        data.encode('utf-8'),
        padding.OAEP(
            mgf=padding.MGF1(algorithm=hashes.SHA256()),
            algorithm=hashes.SHA256(),
            label=None
        )
    )
    
    # Return base64 encoded
    return base64.b64encode(encrypted).decode('utf-8')

Node.js (node-jose)

const jose = require('node-jose');

async function encryptWithJWK(data, jwk) {
  // Create key from JWK
  const key = await jose.JWK.asKey(jwk);
  
  // Encrypt the data
  const encrypted = await jose.JWE.createEncrypt({
    format: 'compact',
    contentAlg: 'A256GCM'
  }, key)
    .update(JSON.stringify(data))
    .final();
  
  return encrypted;
}

Best Practices

Key Rotation: The public key may be cached for up to. 15 minutes. Upon invalid key error, fetch the key and retry one time. Key validation should be removed
Format Selection: Choose the format that works best with your encryption library
Error Handling: Always handle network errors when fetching the key
Key Validation: Verify the key ID matches between encryption and submission

Common Use Cases

Credit Card Encryption: Primary use is for encrypting credit card data for payment endpoints
Tokenization: Used with payment tokenization endpoints
Secure Data Transmission: Any sensitive data sent to Firmly payment endpoints

Checkout Flow Integration

This endpoint is the first step in the secure payment flow:

Fetch Public Key

Call this endpoint to get the current encryption key

Encrypt Credit Card

Use the public key to encrypt card data according to your chosen format

Complete Order

Send encrypted card data to one of the complete-order endpoints

Complete Example Flow

// 1. Get the public key
const publicKeyResponse = await fetch('https://cc.firmly.work/api/v1/payment/key');
const publicKey = await publicKeyResponse.json();

// 2. Encrypt credit card data
const encryptedCard = await encryptCard({
  number: "4111111111111111",
  name: "John Smith",
  verification_value: "123",
  month: "12",
  year: "2025"
}, publicKey);

// 3. Complete the order
const orderResponse = await fetch('https://cc.firmly.work/api/v1/payment/domains/staging.luma.gift/complete-order', {
  method: 'POST',
  headers: {
    'x-firmly-authorization': authToken,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    encrypted_card: encryptedCard,
    billing_info: billingInfo
  })
});

const order = await orderResponse.json();

Complete Order (Simple Cart) - Complete checkout for Simple Cart API
Complete Order (Full Cart) - Complete checkout for Full Cart API
Place Order (Simple Cart) - Create cart and order in one call
Place Order (Full Cart) - Create cart and order with advanced features

⌘I

Get Public Key

curl --request GET \
  --url https://cc.firmly.work/api/v1/payment/key \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://cc.firmly.work/api/v1/payment/key', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://cc.firmly.work/api/v1/payment/key",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://cc.firmly.work/api/v1/payment/key"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://cc.firmly.work/api/v1/payment/key")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "x-firmly-kid": "<string>",
  "kid": "<string>",
  "kty": "<string>",
  "n": "<string>",
  "e": "<string>",
  "use": "<string>"
}

Home

Core Concepts

Implementation Guides

Ask Agent SDK

API Reference

firmly Connect

Resources

Overview

Authentication

Query Parameters

Response Headers

Response Formats

JWK Format (Default)

PEM Format

RSA Format

Code Examples

Response Examples

JWK Format Response

PEM Format Response

RSA Format Response

Usage with Encryption Libraries

JavaScript (Web Crypto API)

Python (cryptography)

Node.js (node-jose)

Best Practices

Common Use Cases

Checkout Flow Integration

Complete Example Flow

​Overview

​Authentication

​Query Parameters

​Response Headers

​Response Formats

​JWK Format (Default)

​PEM Format

​RSA Format

​Code Examples

​Response Examples

​JWK Format Response

​PEM Format Response

​RSA Format Response

​Usage with Encryption Libraries

​JavaScript (Web Crypto API)

​Python (cryptography)

​Node.js (node-jose)

​Best Practices

​Common Use Cases

​Checkout Flow Integration

​Complete Example Flow

​Related Endpoints

Overview

Authentication

Query Parameters

Response Headers

Response Formats

JWK Format (Default)

PEM Format

RSA Format

Code Examples

Response Examples

JWK Format Response

PEM Format Response

RSA Format Response

Usage with Encryption Libraries

JavaScript (Web Crypto API)

Python (cryptography)

Node.js (node-jose)

Best Practices

Common Use Cases

Checkout Flow Integration

Complete Example Flow

Related Endpoints