Guides
Barcode Flow for Merchants
Connecting with patrons using our Barcode Flow requires the patron to present a Barcode and the merchant integration to scan it in order to create a Payment Request .
Barcode Flow
The sequence diagram below indicates the expected flow of behavior between the patron, the Point of Sale (POS) and Centrapay.
sequenceDiagram autonumber participant Patron participant POS participant POS Server participant Centrapay Note over Patron: Present Barcode Patron->>POS: Scan Barcode POS->>POS Server: Request Payment POS Server->>Centrapay: Create Payment Request with Barcode par loop Poll until final state POS Server->>Centrapay: Get Payment Request end Patron->>Centrapay: Pay Payment Request end POS Server->>POS: Send Payment Status Note over POS: ✅ Display Successful Payment
The patron presents a Barcode for the POS to scan.
The POS server creates a Centrapay Payment Request with the Barcode.
Request curl -X POST https://service.centrapay.com/api/payment-requests \-H "X-Api-Key: $api_key" \-H "Content-Type: application/json" \-d '{"barcode": "123456789","configId": "5ee168e8597be5002af7b454","value": {"amount": "10000","currency": "NZD"}}'Response {"barcode": "123456789","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é","patronCodeId": "V17FByEP9gm1shSG6a1Zzx","paymentOptions": [{"amount": "10000","assetType": "centrapay.nzd.main"}],"purchaseOrderRef": "oF6kj1QlH5gK0y9rjRHFh2","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"}}The POS server polls the Payment Request for Payment Confirmation.
Request curl https://service.centrapay.com/api/payment-requests/MhocUmpxxmgdHjr7DgKoKw \-H "Authorization: $jwt"Response {"barcode": "123456789","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é","patronCodeId": "V17FByEP9gm1shSG6a1Zzx","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"}}While the POS server continues to poll, the patron pays the Payment Request via their Centrapay integrated app.
Request 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"}'Response {"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","type": "payment","value": {"currency": "NZD","amount": "10000"}}When the Payment Request status is in a final state (
paid,cancelledorexpired). The POS server stops polling and the POS displays the result.Request curl https://service.centrapay.com/api/payment-requests/MhocUmpxxmgdHjr7DgKoKw \-H "Authorization: $jwt"Response {"barcode": "123456789","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é","patronCodeId": "V17FByEP9gm1shSG6a1Zzx","paymentOptions": [{"amount": "10000","assetType": "centrapay.nzd.main"}],"purchaseOrderRef": "oF6kj1QlH5gK0y9rjRHFh2","shortCode": "CP-C7F-ZS5","status": "paid","updatedAt": "2021-06-08T04:04:27.426Z","url": "https://app.centrapay.com/pay/MhocUmpxxmgdHjr7DgKoKw","value": {"currency": "NZD","amount": "10000"}}
Quick Pay Flow
Quick Pay is used to immediately complete the payment without requiring patron approval.
The patron’s barcode must be linked to an asset type that allows Quick Pay in order to use this flow. See Asset Types for the list of asset types that support Quick Pay.
sequenceDiagram
autonumber
participant Patron
participant POS
participant POS Server
participant Centrapay
Note over Patron: Present Barcode
Patron->>POS: Scan Barcode
POS->>POS Server: Request Payment
POS Server->>Centrapay: Create Payment Request with Barcode
loop Poll until final state
POS Server->>Centrapay: Get Payment Request
note over Centrapay: Confirm Details and Complete Payment
end
POS Server->>POS: Send Payment Status
Note over POS: ✅ Display Successful Payment
The patron presents a Barcode for the POS to scan.
The POS server creates a Centrapay Payment Request with the Barcode.
Request curl -X POST https://service.centrapay.com/api/payment-requests \-H "X-Api-Key: $api_key" \-H "Content-Type: application/json" \-d '{"barcode": "123456789","configId": "5ee168e8597be5002af7b454","value": {"amount": "10000","currency": "NZD"}}'Response {"barcode": "123456789","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é","patronCodeId": "V17FByEP9gm1shSG6a1Zzx","paymentOptions": [{"amount": "10000","assetType": "paypal.main"}],"purchaseOrderRef": "oF6kj1QlH5gK0y9rjRHFh2","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"}}The POS server polls the Payment Request for payment completion.
Request curl https://service.centrapay.com/api/payment-requests/MhocUmpxxmgdHjr7DgKoKw \-H "Authorization: $jwt"Response {"barcode": "123456789","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é","patronCodeId": "V17FByEP9gm1shSG6a1Zzx","paymentOptions": [{"amount": "10000","assetType": "paypal.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"}}When Centrapay receives the first attempt to poll the Payment Request, it will trigger a payment. When the Payment Request status is in a final state (
paid,cancelledorexpired). The POS server stops polling and the POS displays the result.Request curl https://service.centrapay.com/api/payment-requests/MhocUmpxxmgdHjr7DgKoKw \-H "Authorization: $jwt"Response {"barcode": "123456789","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é","patronCodeId": "V17FByEP9gm1shSG6a1Zzx","paymentOptions": [{"amount": "10000","assetType": "paypal.main"}],"purchaseOrderRef": "oF6kj1QlH5gK0y9rjRHFh2","shortCode": "CP-C7F-ZS5","status": "paid","updatedAt": "2021-06-08T04:04:27.426Z","url": "https://app.centrapay.com/pay/MhocUmpxxmgdHjr7DgKoKw","value": {"currency": "NZD","amount": "10000"}}
Checking Barcode Details
The POS server can optionally decode a scanned barcode in order to get further details about a barcode before it creates a Payment Request. For example, the POS server can use the barcode provider to apply any provider-specific discounts before creating the Payment Request.
sequenceDiagram autonumber participant Patron participant POS participant POS Server participant Centrapay Note over Patron: Present Barcode Patron->>POS: Scan Barcode POS->>POS Server: Request Barcode Details POS Server->>Centrapay: Decode Barcode POS Server->>POS: Send Barcode Validity Note over POS: Apply Provider Discounts POS->>POS Server: Request Payment POS Server->>Centrapay: Create Payment Request with Barcode
The patron presents a barcode for the POS to scan.
The POS server decodes the scanned barcode and applies any provider-related discounts.
Request curl -X POST https://service.centrapay.com/api/decode \-H "Authorization: $jwt" \-H "Content-Type: application/json" \-d '{"code": "123456789","merchantConfigId": "5ee168e8597be5002af7b454","scannedBy": "merchant"}'Response {"code": "123456789","displayName": "PayPal","merchantConfigId": "5ee168e8597be5002af7b454","provider": "paypal","scannedBy": "merchant"}The POS server creates a Payment Request with the barcode and continues with either the Barcode Flow or Quick Pay Flow .
Request curl -X POST https://service.centrapay.com/api/payment-requests \-H "X-Api-Key: $api_key" \-H "Content-Type: application/json" \-d '{"barcode": "123456789","configId": "5ee168e8597be5002af7b454","value": {"amount": "10000","currency": "NZD"}}'Response {"barcode": "123456789","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é","patronCodeId": "V17FByEP9gm1shSG6a1Zzx","paymentOptions": [{"amount": "10000","assetType": "paypal.main"}],"purchaseOrderRef": "oF6kj1QlH5gK0y9rjRHFh2","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"}}