v1

latestOpenAPI 3.0.0MoneyBadger2026-07-145413.5 KB

reports that a QR code has been scanned by the partner app, obtain payment instructions specific to the wallet

post/scan

Request body

scan_idstring required

a unique ID for the scan, preferably a UUID

transaction_idstring

(Optional) A unique ID for the transaction, preferably a UUID. This ID may be specified by the API consumer when calling the /scan endpoint. This ID must be the reference that the Value Store uses to identify the transaction. if provided, the transaction_id will used to query payment status on the value store.

timestring date-time required

The date and time of the message as recorded by the sender in ISO8601 format

device_idstring required

the device ID of the device that scanned the QR code, preferably a UUID

user_idstring required

the user ID of the user that scanned the QR code, preferably a UUID

scan_datastring required

allowed_payment_methodsstring[]

payment_currenciesstring[]

The currencies of the payment request that the receiver is able to to use for payment. optional, defaults to the default of the payment method

payment_referencestring

The customer-supplied reference for the payment request

Example request

{
  "scan_id": "scanId-6c54-4b01-90e6-d701748f0851",
  "transaction_id": "transactionId-6c54-4b01-90e6-d701748f0851",
  "time": "2023-03-08T13:37:00Z",
  "device_id": "deviceId-6c54-4b01-90e6-d701748f0851",
  "user_id": "userId-6c54-4b01-90e6-d701748f0851",
  "scan_data": "00020126530023za.co.electrum.picknpay0122fom7Ku0aQ9SvG+svh4xVPQ530371054041.23630428E5",
  "allowed_payment_methods": [
    "lightning"
  ],
  "payment_currencies": [
    "BTC"
  ],
  "payment_reference": "customer123",
  "requested_payment_amount": {
    "currency": "BTC",
    "denomination": "sats",
    "amount": 123.45
  }
}

Response

scan has been successfully processed

idstring

A unique ID that we assign to the payment request.

created_atstring date-time

ISO8601 timestamp at which the payment request was created

amount_centsinteger

The amount of the payment request in the currency base unit (e.g. cents or sats)

currencystring

The currency of the payment request that the receiver expects to receive

The current status of the payment request

payment_methodsobject

list of payment method types with payment instruction data the client can use to complete payment

expiry_timestring

ISO8601 timestamp at which the payment request will expire

merchant_namestring

Merchant name

merchant_codestring

Merchant code

merchant_category_codestring

Merchant category code

order_descriptionstring

Optional merchant provided order description

{"stackTrail":"components:schemas:PaymentRequest:properties:notification_url","oasType":"schema","type":"unknown","description":"A URL that must be called whenever the status of this payment request changes (paid, cancelled, etc) The notification_url must be called with a POST request with a JSON body. The details of the JSON body may be determined by the implementer, but MUST include a transaction_id The transaction_id must be the same as the transaction_id provided in the /scan request that we can use to query the status on the Value Store."}

merchant_infoobject

Additional merchant information, structure depends on specific merchant.

Example response

{
  "id": "paymentRequest-6c54-4b01-90e6-d701748f0851",
  "created_at": "2023-03-08T13:37:00Z",
  "amount_cents": 100,
  "currency": "ZAR",
  "payment_methods": {
    "lightning": "lnbc901..."
  },
  "expiry_time": "2023-03-08T13:37:00Z",
  "merchant_name": "Pick n Pay",
  "merchant_code": "pnp",
  "order_description": "Groceries"
}