This document details a set of messages that can be used to register payment apps, request payments, and acknowledge payment requests. The messages are communication channel agnostic and can be transferred via browser APIs, REST APIs, QRCode, NFC, or Bluetooth connections.

There are a number of ways that one may participate in the development of this specification:

Introduction

This document details a set of messages that can be used to register payment apps, request payments, and acknowledge payment requests. The messages are communication channel agnostic and can be transferred via browser APIs, REST APIs, QRCode, NFC, or Bluetooth connections.

How to Read this Document

This document is a detailed specification for a set of messages that can be used to register payment apps, request payments, and acknowledge payment requests. The messages are communication channel agnostic and can be transferred via browser APIs, REST APIs, QRCode, NFC, or Bluetooth connections. The document is primarily intended for the following audiences:

Terminology

The terminology in this specification's terminology and messages need to be updated to match the Payments Architecture document and the latest changes to the Web Payments Browser API.

Message Formats

Payment App Registration

A payment app registration message is used by a payer to add a payment app to the list of payment apps that can be used to complete a payment. 

var visaApp = {
  '@context': 'https://w3id.org/web-payments/v1',
  type: 'PaymentApp',
  paymentMethod: 'https://w3id.org/payment-schemes#Visa',
  label: 'ExampleBank Visa Card',
  paymentRequestService: 'https://pay.example.com/services/cards'
};
    
var bitcoinApp = {
  '@context': 'https://w3id.org/web-payments/v1',
  type: 'PaymentApp',
  paymentMethod: 'https://w3id.org/payment-schemes#Bitcoin',
  id: 'bitcoin:19Cgacam5sVryog9QQKjFo1GApy34Qat83',
  label: 'BitExample Bitcoin Account',
  privateKeyBitcoin: '5JSjcscTvQcCb2h7LxFGwEzVqHM6HqC6xanxwZtymRZg5Z1yWot',
  paymentRequestService: 'https://bitcoin.example.com/services/bitcoin'
};
    
var bankingVisaApp = {
  '@context': 'https://w3id.org/web-payments/v1',
  type: 'PaymentApp',
  paymentMethod: 'https://w3id.org/payment-schemes#Visa',
  label: 'ExampleBank Visa Card',
  paymentRequestService: 'intent://pay/#Intent;scheme=bankApp;package=com.example.bank.client.android;end'
};
    
var iso20022App = {
  '@context': 'https://w3id.org/web-payments/v1',
  type: 'PaymentApp',
  paymentMethod: 'https://w3id.org/payment-schemes#iso20022',
  label: 'Mega Widgets Corporate Account',
  paymentRequestService: 'https://bigbank.example.com/services/iso20022'
};

Payment Request

A payment request message is used by a payee to request payment from a payer. 

var req = {
  '@context': 'https://w3id.org/web-payments/v1',
  type: 'PaymentRequest',
  description: 'Payment to ExampleMerch for widgets',
  acceptedMethod: {
    paymentMethod: 'https://w3id.org/payment-schemes#Visa',
    transfer: {
      amount: '4.35',
      currency: 'USD'
    },
    paymentRequestService: 'https://merchant-psp.example.com/services/getPaymentInfo'
  }
};
    
var req = {
  '@context': 'https://w3id.org/web-payments/v1',
  type: 'PaymentRequest',
  description: 'Payment to ExampleMerch for widgets',
  acceptedMethod: {
    paymentMethod: 'https://w3id.org/payment-schemes#Visa',
    transfer: {
      amount: '4.35',
      currency: 'USD'
    },
    destination: '20389472398',
  }
};
    
var req = {
  '@context': 'https://w3id.org/web-payments/v1',
  type: 'PaymentRequest'
  description: 'Payment to ExampleMerch for Widget 1'
  acceptedMethod: {
    paymentMethod: 'https://w3id.org/payment-schemes#Bitcoin',
    transfer: {
      amount: '0.0177',
      currency: 'BTC'
    },
    destination: '3QJmV3qfvL9SuYo34YihAf3sRCW3qSinyC'
  }
};
    
var req = {
  '@context': 'https://w3id.org/web-payments/v1',
  type: 'PaymentRequest'
  description: 'Payment to ExampleMerch for Widget 1'
  acceptedMethod: [{
    paymentMethod: [
      'https://w3id.org/payment-schemes#Visa',
      'https://w3id.org/payment-schemes#Mastercard',
      'https://w3id.org/payment-schemes#Discover'
    ],
    transfer: {
      amount: '4.35',
      currency: 'USD'
    },
    destination: '20389472398'
  }, {
    paymentMethod: 'https://w3id.org/payment-schemes#Bitcoin',
    transfer: {
      amount: '0.0177',
      currency: 'BTC'
    },
    destination: '3QJmV3qfvL9SuYo34YihAf3sRCW3qSinyC'
  }]
};
    
var req = {
  '@context': 'https://w3id.org/web-payments/v1',
  type: 'PaymentRequest',
  description: 'Payment to ExampleMerch for widgets',
  acceptedMethod: {
    '@context': 'https://w3id.org/iso20022/v1',
    paymentMethod: 'https://w3id.org/payment-schemes#iso20022',
     CstmrCdtTrfInitn: {
       GrpHdr: {
         MsgId: 'ABC/120928/CCT001',
         CreDtTm: '2012-09-28T14:07:00',
         NbOfTxs: '1',
         CtrlSum: '500000',
         InitgPty: {
           Nm: 'ABC Corporation',
           PstlAdr: {
             StrtNm: 'Times Square',
             BldgNb: '7',
             PstCd: 'NY 10036',
             TwnNm: 'New York',
             Ctry: 'US"
          }
        }
      },
       PmtInf: {
         PmtInfId: 'ABC/086',
         PmtMtd: 'TRF',
         BtchBookg: 'false',
         ReqdExctnDt: '2012-09-29',
         Dbtr: {
           Nm: 'ABC Corporation',
           PstlAdr: {
             StrtNm: 'Times Square',
             BldgNb: '7',
             PstCd: 'NY 10036',
             TwnNm: 'New York',
             Ctry: 'US"
          }
        },
         DbtrAcct: {
           Id: {
             Othr: { "Id: '00125574999" }
          }
        },
         DbtrAgt: {
           FinInstnId: { "BICFI: 'BBBBUS33" }
        },
         CdtTrfTxInf: [
          {
             PmtId: {
               InstrId: 'ABC/120928/CCT001/3',
               EndToEndId: 'ABC/987-AC/2012-09-27"
            },
             Amt: {
               InstdAmt: {
                 Ccy: 'USD',
                 text: '500000"
              }
            },
             ChrgBr: 'SHAR',
             CdtrAgt: {
               FinInstnId: { "BICFI: 'BBBBUS66" }
            },
             Cdtr: {
               Nm: 'ABC Corporation',
               PstlAdr: {
                 Dept: 'Treasury department',
                 StrtNm: 'Bush Street',
                 BldgNb: '13',
                 PstCd: 'CA 94108',
                 TwnNm: 'San Francisco',
                 Ctry: 'US"
              }
            },
             CdtrAcct: {
               Id: {
                 Othr: { "Id: '4895623" }
              }
            },
             Purp: { "Cd: 'INTC" },
             RmtInf: {
               Strd: {
                 RfrdDocInf: {
                   Tp: {
                     CdOrPrtry: { "Cd: 'CINV" }
                  },
                   Nb: '987-AC',
                   RltdDt: '2012-09-27"
                }
              }
            }
          }
        ]
      }
    }
  }
};

Payment Acknowledgement

var acknowledgement = {
  '@context': 'https://w3id.org/web-payments/v1',
  type: 'PaymentAcknowledgement',
  description: 'Payment to ExampleMerch for widgets',
  selectedpaymentMethod: {
    paymentMethod: 'https://w3id.org/payment-schemes#Visa',
    status: 'authorized',
    token: '10025AB',
    transfer: {
      amount: '4.35',
      currency: 'USD'
    },
    destination: '20389472398'
  }
};
    
var acknowledgement = {
  '@context': 'https://w3id.org/web-payments/v1',
  type: 'PaymentAcknowledgement',
  description: 'Payment to ExampleMerch for widgets',
  selectedpaymentMethod: {
    id: 'bitcoin-transaction:78526206ef357c35398d3b020e6e09f38d77729cc4a70a6facd463bb146a4c90',
    paymentMethod: 'https://w3id.org/payment-schemes#Bitcoin',
    transfer: {
      amount: '0.035',
      currency: 'BTC'
    },
    destination: '1LuckyR1fFHEsXYyx5QK4UFzv3PEAepPMK',
    confirmations: 31
  }
};
    
var acknowledgement = {
  '@context': 'https://w3id.org/web-payments/v1',
  type: 'PaymentAcknowledgement',
  description: 'Payment for shipment of widgets',
  selectedpaymentMethod: {
    '@context': 'https://w3id.org/iso20022/v1',
    paymentMethod: 'https://w3id.org/payment-schemes#iso20022',
    CstmrPmtStsRpt: {
      GrpHdr: {
        MsgId: 'XMPL/120928-PSR/001',
        CreDtTm: '2015-10-01T09:20:11',
        InitgPty: {
          Nm: 'Example Corporation',
          PstlAdr: {
            StrtNm: 'Main Street',
            BldgNb: '1242',
            PstCd: 'VA 24060',
            TwnNm: 'Somewhereville',
            Ctry: 'US'
          }
        },
        DbtrAgt: {
          FinInstnId: { 'BICFI': 'XMPLUS12' }
        }
      },
      OrgnlGrpInfAndSts: {
        OrgnlMsgId: 'XMPL/120928/CCT001',
        OrgnlMsgNmId: 'pain.001.001.05',
        OrgnlCreDtTm: '2015-10-01T12:14:42',
        OrgnlNbOfTxs: '2',
        OrgnlCtrlSum: '500000',
        GrpSts: 'ACCP'
      }
    }
  }
};

Security Considerations

Message Integrity

It is possible to sign any JSON-LD based message by using Linked Data Signatures, like so: 

var req = {
  '@context': 'https://w3id.org/web-payments/v1',
  type: 'PaymentRequest',
  description: 'Payment to ExampleMerch for widgets',
  acceptedMethod: {
    paymentMethod: 'https://w3id.org/payment-schemes#Visa',
    transfer: {
      amount: '4.35',
      currency: 'USD'
    },
    paymentRequestService: 'https://merchant-psp.example.com/services/getPaymentInfo'
  },
  signature: {
    type: 'LinkedDataSignature2015',
    creator: 'https://merchant.example.com/keys/23',
    created: '2015-09-23T20:21:34Z',
    nonce: '239807882930744351',
    signatureValue: 'NGVkMzVmOGQz4NTIyZTkZ...OWM32NjIgoYzI43Q3ODIy='
  }
};

Acknowledgements

The editor would like to thank the Web Payments Community Group and the Web Payments Interest Group.

Thanks to the following individuals, in order of their first name, for their input on the specification: ...