mpp-card

TypeScript SDK for card payments in the Machine Payments Protocol. Gate any HTTP endpoint behind a Visa, Mastercard, Amex, or Discover payment — the server returns 402 Payment Required with a challenge, the client obtains an encrypted network token and retries, and the server charges the card and returns a receipt. Works with any payment processor.

Documentation

Full protocol specification at paymentauth.org/draft-card-charge-00.html.

Install

npm i mpp-card

Quick Start

Server

import { MppCard } from 'mpp-card/server'

const mpp = MppCard.create({
  acceptedNetworks: ['visa', 'mastercard'],
  merchantName: 'Demo',
  privateKey: process.env.PRIVATE_KEY,
  secretKey: process.env.MPP_SECRET_KEY,
  gateway: myServerEnabler, // Visa Acceptance, or custom
})

const charge = mpp.charge({ amount: '500', currency: 'usd' })

export async function handler(request: Request) {
  const result = await charge(request)
  if (result.status === 402) return result.challenge
  return result.withReceipt(Response.json({ data: '...' }))
}

Use generateKeyPair() from mpp-card/server to generate a key pair, or bring your own RSA-2048 PEM. When gateway is omitted and NODE_ENV is not "production", charges are mocked automatically.

Client

import { MppCard, vgsClientEnabler } from 'mpp-card/client'

MppCard.create({
  cardId: 'CRD...',
  enabler: vgsClientEnabler({ clientId: '...', clientSecret: '...' }),
})

// Global fetch now handles 402 automatically
const res = await fetch('https://api.merchant.com/data')

Omit enabler for a built-in dev mock.

Node.js HTTP

import * as http from 'node:http'

const listener = MppCard.toNodeListener(charge)

http.createServer(async (req, res) => {
  const result = await listener(req, res)
  if (result.status === 402) return
  res.writeHead(200, { 'Content-Type': 'application/json' })
  res.end(JSON.stringify({ data: '...' }))
}).listen(3000)

Custom Integrations

Payment Gateway (Server Enabler)

Connect any payment processor by implementing ServerEnabler:

import type { ServerEnabler } from 'mpp-card/server'

const custom: ServerEnabler = {
  async charge({ token, network, amount, currency, idempotencyKey, ...extra }) {
    // token.token.paymentToken — network token (DPAN)
    // token.dynamicData.dynamicDataValue — cryptogram
    // All credential payload fields pass through via ...extra
    return { reference: 'ch_xxx', status: 'success' }
  },
}

Credential Issuer (Client Enabler)

Connect any credential issuer by implementing ClientEnabler:

import type { ClientEnabler } from 'mpp-card/client'

const custom: ClientEnabler = {
  async getPaymentData({ cardId, challenge }) {
    // challenge.encryptionJwk — server's RSA public key
    return {
      encryptedPayload: '...',  // JWE (RSA-OAEP-256 + AES-256-GCM)
      network: 'visa',
      // Extra fields pass through to the credential and server enabler
    }
  },
}

Built-in enablers: vgsClientEnabler, visaAcceptanceClientEnabler, visaAcceptanceServerEnabler. See examples/ for usage.

Exports

// Server
import { MppCard, card, generateKeyPair, decryptToken } from 'mpp-card/server'
import type { ServerEnabler } from 'mpp-card/server'

// Client
import { MppCard, vgsClientEnabler, visaAcceptanceClientEnabler } from 'mpp-card/client'
import type { ClientEnabler } from 'mpp-card/client'

// Core
import { Challenge, Credential, Receipt, Errors } from 'mpp-card'

Protocol

Built on the "Payment" HTTP Authentication Scheme. See draft-mpp-card-charge-00 for the card charge intent specification.

License

See LICENSE for terms.