Openpay
Introduction
Openpay is a credit payment provider that allows customers to spread the cost of their order value over multiple payments. Aurora's integration with Openpay allows your customers to make use of Openpay's payment plans when placing orders via the Aurora Front-end.
When using the Openpay integration, refunds for orders found in Aurora should be performed via Aurora only. Performing refunds via any other method (that is not entirely controlled by Aurora) will not be reflected against your orders in Aurora.
Initial Setup
The Openpay Integration uses the Aurora Microservice (MS) framework, and as such must be set-up in advance by Aurora Commerce before you can use it with your store.
Doing this requires a one-off development to setup and configure your store to use the Openpay MS, after which, you can then configure the integration at your own leisure.
If you have not yet had (or do not know if you have had) the Openpay MS set up and configured for your store, then please contact Aurora Commerce for more details regarding how to get this done.
In order to configure your Openpay MS, you will need to request the following details from Openpay:
- Openpay API Endpoint prefix
- Openpay API Username
- Openpay API Password
Please request these details for both Staging (Test) and Production (Live) environments, so that you can test your integration before go live.
Aurora Backend Settings
Once the Openpay MS has been setup and enabled for your store, you can follow these steps to allow your customers to use it on your front-end checkout.
Enable the Openpay Microservice
Store > Settings > Feeds > Microservice > Proxy Openpay
Configure visibility of the Openpay payment option (in conjunction with the "Payment Types Accepted at Checkout" setting):
| Parameter Name | Value For Integration | Note |
|---|---|---|
| Enabled? | checked | Controls whether the Openpay payment option is visible on your checkout page: checked = accessible and visible unchecked = not accessible and not visible |
This 'visibility behaviour' is enforced entirely within the Aurora Front-end Templates and so is the default behaviour offered by the Aurora Demo Example Front-end Templates, but may not be how your own Front-end Templates are configured.
If you run into issues with payment option visibility, please check your Front-end Templates for the appropriate logic.
Payment Types Accepted at Checkout
Store > Settings > Payment Providers
Configure Aurora to accept orders using the Openpay payment type:
| Parameter Name | Value For Integration | Note |
|---|---|---|
| Validate Payment Type | checked | Controls whether the checkout enforces a strict/reduced list of payment types that are accepted on checkout submission. checked = payment types are enforced to the defined list unchecked = payment types are not enforced to the defined list |
| Openpay | checked | Controls whether Openpay is on the list of payment types that will be accepted on checkout submission. checked = Openpay is accepted and visible on checkout submission unchecked = Openpay is not accepted and not visible on checkout submission |
This 'visibility behaviour' is enforced entirely within the Aurora Front-end Templates and so is the default behaviour offered by the Aurora Demo Example Front-end Templates, but may not be how your own Front-end Templates are configured.
If you run into issues with payment option visibility, please check your Front-end Templates for the appropriate logic.
Microservice Settings
Store > Microservice > Proxy Openpay
Configure the Openpay MS to communicate with the Openpay API:
| Parameter Name | Value for Integration | Notes |
|---|---|---|
| Is Live | Checked - for Live Unchecked - for Test | Whether Aurora uses the live or test credentials and endpoints. |
| Live API Endpoint Prefix | Example value (do not use): https://api.training.myopenpay.co.uk | Unique prefix for the endpoint used by the Openpay MS to contact the Openpay API. Please contact Openpay to obtain this URL. |
| Live API Username | Example value (do not use): 1-109 | Username to be used with the Live API endpoint. |
| Live API Password | Example value (do not use): AQEphmfuXNWTK0Qc+iSRh3Y3teW4R 4ZACDad23IFJXUVCV0MjUrgp | API Password to be used with the Live API endpoint. |
| Test API Endpoint Prefix | https://api.training.myopenpay.co.uk | Unique prefix for the endpoint used by the Openpay MS to contact the Openpay staging API. This can be found in the Openpay documentation here: https://developer.openpay.co.uk/TestCredentialsUK |
| Test API Username | Example value (do not use): 1-109 | Username to be used with the Test API endpoint. |
| Test API Password | Example value (do not use): AQEphmfuXNWTK0Qc+iSRh3Y3teW4R 4ZACIFJstgj87XUVCV0MjUrgp | API Password to be used with the Test API endpoint. |
Minimum and Maximum order values
Openpay has restrictions on the values that can be passed through to its payment service. These take the form of maximum and minimum order values. When these are set (in Openpay) it will result in payments being rejected if the total order value does not fall within these limits.
If you wish to change these limits, you must do so by contacting Openpay directly as Aurora does not manage these limits for you.
To help ensure that the customer experience is a smooth as possible, Aurora imports these values once a day for you in order to allow you to tailor your checkout process based on the order value and the availability of credit from Openpay.
For more detail on how to tailor your checkout as suggested here, please see the Frontend Template Integration > Checking the Openpay Payment Limits section of this support article.
You are able to view the values currently imported into Aurora (which are usually updated once a day from Openpay) from within the Aurora Back-end under the Proxy Openpay settings section.
Aurora Service Errors
Content > Site Text
User error messages from the Aurora payment service that can be changed and translated using the Aurora Site Text system:
| Page | Part | Note |
|---|---|---|
| Checkout | CheckoutPayment proxy-openpay Error: MSRequestInvalid | A general error when a request to the payment service cannot be provided. This may be resolvable if the user tries the operation again. |
| Checkout | CheckoutPayment proxy-openpay Error: MSResponseInvalid | A general error when a response from the payment service cannot be provided. This may be resolvable if the user tries the operation again. |
| Checkout | CheckoutPayment proxy-openpay Error: MSConfigurationError | The Openpay MS has not been configured correctly and is unable to connect to the Openpay API. |
| Checkout | CheckoutPayment proxy-openpay Error: MSPaymentProviderError | The Openpay API has responded with an unknown error. More details on these errors can be found within: Store > Logs > API Integration Log |
| Checkout | CheckoutPayment proxy-openpay Error: MSPaymentProviderConnectionError | The Aurora Openpay service was unable to connect to the Openpay API. More details on these errors can be found within: Store > Logs > API Integration Log |
| Checkout | CheckoutPayment proxy-openpay Error: MSPaymentCancelled | The customer cancelled payment within Openpay and was returned to checkout. |
| Checkout | CheckoutPayment proxy-openpay Error: MSPaymentDeclined | The customers payment request was declined by Openpay and was returned to checkout. |
Frontend Template Integration
Displaying the Openpay Payment Option
In order to use the Openpay MS within your checkout, you must simply include the following values within your checkout submission:
| Name | Value |
|---|---|
| payment_type | proxy-openpay |
| payment_custom_fields[proxy-openpay] | true |
Example template:
{if $config.microservice_proxyopenpay_live}
{include file="checkout/openpay/payment-methods.tpl.html"}
{/if}
Find the content of the "checkout/openpay/payment-methods.tpl.html" file within the Aurora Demo templates.
Checking the Openpay Payment Limits: Payment Limits Callback
Before you begin, please be aware that the Aurora Demo Front-end Templates already have a working implementation of this behaviour, enabling and disabling Openpay based on the Ajax call to Aurora. This being so, you need only read the following for your reference should you wish to implement your own solution.
Find the existing implementation of this in the templates/example.com/_js/openpay.payments.js file for your reference.
Request Data
To make a call to the Aurora Callback endpoint to fetch the limits, you should make a request to the following endpoint with the parameters as described below:
Endpoint: /checkout/payment-client-callback
Method: POST
| Parameter Name | Value | Description |
|---|---|---|
| route | "payment-methods" | This is a static string value that must always be provided as described here, so that the Callback endpoint knows what is being requested. |
| use_dummy_payment_data | true | This is a static boolean value that must always be provided as described here in order to tell Aurora to avoid creating any payment session data along-side this call. |
| payment_detail | This is a container. | |
| payment_detail.amount_total | Float | This is the value you are looking to check. It should be the total value of the customers current basket. |
| payment_type | "proxy-openpay" | This is a static string value that must always be provided as described here, so the the Callback endpoint knows which payment service to send this request to. |
Response Data
You can use the Aurora Client Callback to fetch the following information:
Format: JSON
| Response Variable Name | Value | Description |
|---|---|---|
| allowPayment | Boolean | This indicates whether Openpay will accept a request for the value specified, based on the currently configured limits and should be used to decide whether to display/enable the Openpay payment option on your checkout. |
| minimumAmount | Float | The currently configured minimum value is returned for your reference. The Aurora Demo Example Front-end Templates do not currently use this value, but you could do so if you wished to indicate to the customer how much more they should spend in order to qualify for Openpay. |
| maximumAmount | Float | The currently configured maximum value is returned for your reference. The Aurora Demo Example Front-end Templates do not currently use this value, but you could do so if you wished to indicate to the customer how much less they should spend in order to qualify for Openpay. |
Notes for Testing
When testing the Openpay integration, you should keep the following in mind.
E-mail Verification
During testing, using your Openpay Test Account, you may run into the need to verify your email address. When this occurs, simply use 123456 as the verification code.
SMS Mobile Phone Verification
During testing, using your Openpay Test Account, you may run into the need to verify your mobile phone number. When this occurs, simply use 111111 as the verification code.
Updated over 2 years ago