API docs by Redocly

QR Code (0.8.2 - draft)

Download OpenAPI specification:Download

CDPI: info@cdpi.dev License: CC BY-SA 4.0
  1. Interoperable QR code specification to Scan & Pay, Click & Pay and to Deep Link between apps and to enable easy one click and authorise one time or recurring payment.
  2. For more info on technical specs, click here
  3. For discussions, click here

/qr/pay

End point to post the payment instructions read from QR scan

Request Body schema: application/json
ver
string
txnId
string <= 50 characters
  1. System generated unique transaction id for each payment request
  2. Applicable in dynamic qr's
txnTs
string <date-time>
  1. Transaction time stamp
  2. Applicable in dynamic qr's
payeeFa
required
string <^[a-zA-Z0-9.-]+@[a-zA-Z0-9.-]+$>
  1. Payee Financial Address
  2. Please refer to the link for more info.
payeeName
required
string <= 100 characters

Resolved payee name from the network for additional reference

totalAmt
required
string (Amount) ^\d{1,13}\.\d{1,2}$

Describes amount in decimal value format

Array of objects (SplitAmount)
  1. Breakup of amount into various categories
  2. Sum of the splits to add up to the amount
  3. Countries/Implemenations can customise as per local context
mode
string
Enum: "terminal" "pos" "online" "atm" "other"
  1. Mode of payment initiation, indicative list
  2. Countries/Implemenations can customise as per local context
cur
string^[A-Z]{3,3}$
  1. Currency code allocated as per ISO 4217 format
  2. Codes for the representation of currencies and funds
mid
string <= 50 characters

Merchant Id

tid
string <= 50 characters

Terminal Id

expiryTs
string <date-time>

Pay by date-time after which the QR code is no longer valid

refNum
string <= 100 characters

Primary reference no can refer to inovice num, order id, bill num to carry business context

refUrl
string <= 100 characters

referne url

note
string <= 25 characters

Note made by user or system to easily refer to the payment/txn

object

Instructions to authroise recurring payments, subscription scenarios

Array of objects (KeyValue)
  1. Additional data that may be useful especially when generating dynamic qr codes to carry business context
  2. Customer, Business, Transaction and Payment related additional context info can be placed here
  3. e.g., location, invoice num, order id, audit related info
signature
required
string
  1. Digital signature as per country's established standards & guidelines
  2. Recommnedation is to use atleast 2K keys for signing

Responses

Request samples

Content type
application/json
{
  • "ver": "0.8.2",
  • "txnId": "2023/123456",
  • "txnTs": "20230605T101125+5:30",
  • "payeeFa": "joeuser@national-bank",
  • "payeeName": "Printing & Stationeries Co",
  • "totalAmt": "117.50",
  • "splitAmts": [
    ],
  • "mode": "terminal",
  • "cur": "ZAR",
  • "mid": "M-12345",
  • "tid": "POS-123",
  • "expiryTs": "20230605T101225+5:30",
  • "refNum": "2023/123456",
  • "refUrl": "https://printing.co/orderId=2023/123456",
  • "note": "catrdige 10 nos",
  • "repeat": {
    },
  • "addlInfo": [
    ],
  • "signature": "string"
}

/qr/pay/{url_encoded_qr_req}

  1. End point to post the payment instructions read from QR scan
  2. The same Qr code spec can be used in Scan & Pay, Click & Pay and Deep Linking modes
path Parameters
url_encoded_qr_req
required
string
Example: %7B%0A%20%20%22version%22%3A%20%221.0.0%22%2C%0A%20%20%22payee_fa%22%3A%20%22joeuser%40national-bank%22%2C%0A%20%20%22payee_name%22%3A%20%22Printing%20%26%20Stationeries%20Co%22%2C%0A%20%20%22amount%22%3A%20%22138.50%22%2C%0A%20%20%22amount_split%22%3A%20%7B%0A%20%20%20%20%22sale%22%3A%20%22117.37%22%2C%0A%20%20%20%20%22igst%22%3A%20%2221.13%22%0A%20%20%7D%2C%0A%20%20%22init_mode%22%3A%20%22POS%22%2C%0A%20%20%22currency%22%3A%20%22ZAR%22%2C%0A%20%20%22mid%22%3A%20%22M-12345%22%2C%0A%20%20%22pos_id%22%3A%20%22POS-123%22%2C%0A%20%20%22expiry%22%3A%20%2220230605T101225%2B5%3A30%22%2C%0A%20%20%22order_id%22%3A%20%222023%2F123456%22%2C%0A%20%20%22ref_url%22%3A%20%22https%3A%2F%2Fprinting.co%2ForderId%3D2023%2F123456%22%2C%0A%20%20%22additional_data%22%3A%20%7B%0A%20%20%20%20%22bill_number%22%3A%20%22123%22%2C%0A%20%20%20%20%22reference_no%22%3A%20%22PO123%22%2C%0A%20%20%20%20%22key1%22%3A%20%22value1%22%0A%20%20%7D%2C%0A%20%20%22sign%22%3A%20%22%22%0A%7D

URL encoded Qr request json object

Responses