Guides

Paying a Payment Request

Overview

This guide is for a Third-party Asset Provider to enable paying with their digital assets with Centrapay.

Authenticating API calls on behalf of users

Third-party applications can make API calls on behalf of users with Centrapay API keys. All API requests to Centrapay must be made from the integrator’s server. Centrapay API keys must also be managed server side and stored as secrets to minimize the risk of API keys being compromised.

Separate API keys will be used for test and live payments.

Contact integrations@centrapay.com to be issued your API keys.

Payment Flow Overview

The payment flow below describes how a Third-party Asset Provider should integrate with the Dynamic Merchant QR Code flow to enable digital payments within their application. Below is an overview of the process, followed by a more in-depth look at the integrator’s responsibilities.

    sequenceDiagram
  autonumber

	actor user
  participant Payment Terminal
  participant App
  participant Integrator as Integrator's Server
  participant Centrapay

	user->>Payment Terminal: Select Centrapay
	Payment Terminal->>Centrapay: Create Payment Request
	note over Payment Terminal: Display QR code
	App->>Payment Terminal: Scan QR code
	note over App: Parse Centrapay QR code
	App->>Integrator: Request payment details
	Integrator->>Centrapay: Get Payment Request
	note over App: Display Payment Request details
  user->>App: Approve payment
	App->>Integrator: Request payment is paid
	Integrator->>Centrapay: Pay Payment Request
	App->>user: Display successful payment
  Payment Terminal->>Centrapay: Get Payment Request
  note over Payment Terminal: Display paid successfully

User selects Centrapay on the terminal at a participant merchant
The payment terminal creates a Payment Request with Centrapay on behalf of the merchant and displays a QR code.
User scans the QR code with their app.
App sends the Payment Request id from the QR code to the server requesting the details of the payment.
The server gets the Payment Request from Centrapay.
The user views the payment details on their app and approves the payment.
The app requests the server pay the Payment Request
The server Pays the Payment Request with the users asset
The app displays a successfully paid screen to the user
The terminal gets the Payment Request and displays successfully paid

Payment Flow Implementation

Scan Centrapay QR code

The user will then scan the QR code from inside the app. Valid Centrapay QR Codes will have the format https://app.centrapay.com/pay/{paymentRequestId}. Validate the url by asserting it matches the above format and ignore any malformed QR codes.

Get the Payment Request

Once the app has validated the url, use the id of the Payment Request to call the Get Payment Request API from your server. The returned PaymentRequest model will provide the details needed to determine if the Payment Request can be completed.

Field	Used for
status	If the status of the the Payment Request is `new` it is still able to be paid, if it is `cancelled`, `expired`, or `paid` it is in a final state and payments can no longer be made against the Payment Request.
paymentOptions	The Payment Options define what Assets a merchant accepts. If your Asset’s type is in the Payment Options array, it is able to be used for payment. If your Asset’s type is not in the Payment Options then the merchant has not been configured to accept your payment method.
liveness	Liveness determines whether a Payment Request is a test Payment Request. Test Payment Requests can only be paid with test assets, and should not be displayed to end users.

Pay the Payment Request

If the Payment Request is payable with your Asset then you should display the Payment Request details to the user. Some relevant fields to display are:

Field	Description
merchantName	The name of the merchant the user is paying
value	The currency and amount the merchant is requesting, which may need to be converted to the denomination of the asset used for payment

Once a user has seen the relevant information and confirmed payment you should invoke the Pay Payment Request API from the server on behalf of the user with the following fields:

Field	Description
assetType	The Asset Type defined when you registered your third party asset
authorization	An identifier for your Asset Type which will be used when invoking the Pay Payment Request API

If the payment was successful then the status of the Payment Request will be paid and you can show confirmation of payment to the user.

Payment Extensions

Extensions to the payment protocol can be used to enhance the user's experience by providing alternative payment flows.

Partial Pay

If both your app and the merchant support Partial Pay then you may allow the user to pay only a portion of the Payment Request and then pay the remaining amount with an alternative payment method.

The partialAllowed flag on the Payment Request will determine if the merchant allows partial payments. If they don’t then you should only allow paying the entire Payment Request.

To pay a partial amount of the Payment Request pass the mode and amount to the pay Payment Request API.

Field	Used for
mode	For partial payments the mode should be `partial-payment`.
amount	For partial payments you must provide the amount of the Payment Request you want to partially pay.

The remainingAmount property on the Payment Request can be used to show how much the user still needs to pay with an alternative method.

Testing

Centrapay supports test resources that can be used for integration testing. A test merchant will be provided that accepts test payments. If you have supplied a test third-party asset then this merchant can be configured to accept it as a payment method.

The Centrapay Business Portal or APIs can be used in place of a payment terminal to test the app.