QR Code Flow for Merchants

Connecting with patrons using our QR Code Flow requires the merchant integration to create a Payment Request and present a QR Code for the patron to scan.

The sequence diagram below indicates the expected flow of behavior between the patron, the Point of Sale (POS) or terminal, and Centrapay.

    sequenceDiagram
	autonumber

	participant Patron
	participant POS as POS/Terminal
  participant Server as POS/Terminal Server
	participant Centrapay

  POS->>Server: Request Payment

	Server->>Centrapay: Create Payment Request

  Server->>POS: Send Payment Request Details

	note over POS: Present QR Code

	Patron->>POS: Scan QR Code

	par
		loop Poll until final state
			Server->>Centrapay: Get Payment Request
		end
	and
		Patron->>Centrapay: Pay Payment Request
	end

  Server->>POS: Send Payment Status

	Note over POS: ✅ Display Successful Payment
	Note over Patron: ✅ Display Successful Payment
  

1. The POS/Terminal server creates a Payment Request. The POS/Terminal then presents a QR code to the Patron on a customer-facing display.

   The QR code decodes to a URL of the form https://app.centrapay.com/pay/{paymentRequestId}

   curl -X POST https://service.centrapay.com/api/payment-requests \
     -H "X-Api-Key: $api_key" \
     -H "Content-Type: application/json" \
     -d '{
       "configId": "5ee168e8597be5002af7b454",
       "value": {
         "amount": "10000",
         "currency": "NZD"
       }
     }'

   {
     "configId": "5ee168e8597be5002af7b454",
     "createdAt": "2021-06-08T04:04:27.426Z",
     "expiresAt": "2021-06-08T04:06:27.426Z",
     "expirySeconds": 120,
     "id": "MhocUmpxxmgdHjr7DgKoKw",
     "merchantId": "26d3Cp3rJmbMHnuNJmks2N",
     "merchantName": "Centrapay Café",
     "paymentOptions": [
       {
         "amount": "10000",
         "assetType": "centrapay.nzd.main"
       }
     ],
     "shortCode": "CP-C7F-ZS5",
     "status": "new",
     "updatedAt": "2021-06-08T04:04:27.426Z",
     "url": "https://app.centrapay.com/pay/MhocUmpxxmgdHjr7DgKoKw",
     "value": {
       "currency": "NZD",
       "amount": "10000"
     }
   }

2. The patron scans the QR code using a Centrapay-enabled app.

3. The POS/Terminal server polls the Payment Request for Payment Confirmation.

   curl https://service.centrapay.com/api/payment-requests/MhocUmpxxmgdHjr7DgKoKw \
     -H "Authorization: $jwt"

   {
     "configId": "5ee168e8597be5002af7b454",
     "createdAt": "2021-06-08T04:04:27.426Z",
     "expiresAt": "2021-06-08T04:06:27.426Z",
     "expirySeconds": 120,
     "id": "MhocUmpxxmgdHjr7DgKoKw",
     "merchantId": "26d3Cp3rJmbMHnuNJmks2N",
     "merchantName": "Centrapay Café",
     "paymentOptions": [
       {
         "amount": "10000",
         "assetType": "centrapay.nzd.main"
       }
     ],
     "shortCode": "CP-C7F-ZS5",
     "status": "new",
     "updatedAt": "2021-06-08T04:04:27.426Z",
     "url": "https://app.centrapay.com/pay/MhocUmpxxmgdHjr7DgKoKw",
     "value": {
       "currency": "NZD",
       "amount": "10000"
     }
   }

4. While the POS/Terminal server continues to poll, the patron pays the Payment Request via their Centrapay integrated app. When the Payment Request status is in a final state (paid, cancelled or expired). The POS/Terminal server stops polling and the POS/Terminal displays the result.

   curl -X POST https://service.centrapay.com/api/payment-requests/MhocUmpxxmgdHjr7DgKoKw/pay \
     -H "Authorization: $jwt" \
     -H "Content-Type: application/json" \
     -d '{
       "assetType": "centrapay.nzd.main",
       "assetId": "WRhAxxWpTKb5U7pXyxQjjY"
     }'

   {
     "activityNumber": "2",
     "assetType": "centrapay.nzd.main",
     "createdAt": "2021-06-08T04:04:27.426Z",
     "createdBy": "crn::user:0af834c8-1110-11ec-9072-3e22fb52e878",
     "merchantAccountId": "C4QnjXvj8At6SMsEN4LRi9",
     "merchantConfigId": "5ee168e8597be5002af7b454",
     "merchantId": "26d3Cp3rJmbMHnuNJmks2N",
     "merchantName": "Centrapay Café",
     "paymentRequestCreatedBy": "crn::user:0af834c8-1110-11ec-9072-3e22fb52e878",
     "paymentRequestId": "MhocUmpxxmgdHjr7DgKoKw",
     "shortCode": "CP-C7F-ZS5-015",
     "type": "payment",
     "value": {
       "currency": "NZD",
       "amount": "10000"
     }
   }