Install and Configure an App
We recommend that you use the sandbox environment for accessing the Tenant portal, if you are trying to install and configure Apps for the first time.
When you are trying to communicate with a Payment Service Provider, you will have to follow a tedious setup process ensuring all the integrations are correct.Duck Creek has designed and constructed the interfaces to integrate with most of the Payment Service Providers. These interfaces are shipped along with Duck Creek Payments and are referred to as Apps.
Before you Start
Before you start following this guide, you should understand the concepts related to the Payments application. You must also have access to the Tenant Portal and permission to install and configure Apps.How it works?
You can find a list of Apps through the Marketplace, where each App is associated with a Payment Service Provider. Once you have installed the App of your choice, you will be asked to submit the credentials that you use to connect with the Payment Service Provider (PSP), along with the PSP's features that you want to use.Depending on the App you are trying to configure, the credentials can be as simple as the username and password that you use to login with the Payment Service Provider or as complex as a set of API and Webhook keys.
All the information that you enter through the Apps are stored in a secret vault that is encrypted and secure.
After you have configured and saved the App, you can then have Payments use the Apps and transact with the PSPs on your behalf.
A special DCT Testing v2 App has been provided that allows you to perform tests without having to connect to the services of a PSP. To use this App, follow Steps 1 through 3 in How to Install and Configure Apps and then proceed to Configuring the DCT Testing v2 App.
Follow this guide to learn how to install and configure an App in the Tenant portal.
How to Install and Configure Apps
Step 1: Go to Apps
- Login to the Tenant Portal.
- Select Apps under Marketplace menu from the left sidebar. The Installed apps page appears with a list of all the installed apps (if any).
Step 2: Find your App in App Marketplace
- In the Installed apps page, click:
- the button next to the Search box, or
- the larger Add box that you will see the Installed apps page.
- The App marketplace page appears with a list of all the Apps. Use one of the following options to search for your desired App.
- Search box next to the Hide filter button to search the name of the PSP
- Filter panel next to the left-side bar to narrow down the search
- Mouse/keyboard to scroll and locate the App
Step 3: Install the App
- Once you have located the App you want to install, click on the Add button next to the App.
- A confirmation box will appear, prompting you to install. Click Yes, install.
- The App's setup page appears and a slide-in banner on the top of the page will notify that App installation has completed.
Step 4: Configure the App
If you are returning to configure an App that you have installed, you will have to Go to Installed apps page and click on the App you want to configure.
If you are configuring the DCT Testing v2 App, skip this step and continue to Configuring the DCT Testing v2 App.
- In the App's setup page, provide all the necessary information. The information required to provide during the configuration depends on the PSP.
You can receive the personal credentials that you will have to enter during the App configuration from your PSP.
- Enable all the features that you want to use with Payments.
- Click to securely store all the information you have provided.
- A slide-in banner on the top of the page will notify that App has been configured successfully. You will also see the border around the App's setup page light up in green (as opposed to the initial red) indicating the App configuration is valid.
Configuring the DCT Testing v2 App
A special DCT Testing v2 App has been provided that serves as a simulator to validate how various payment methods perform in specific situations, allowing you to perform tests without having to connect to the services of a PSP.
Transaction Result Flow
When configuring the app, rules are added that define criteria that will result in a transaction with a SUCCESS or FAILED result. When the app is processing a transaction, Payments checks for the rule that applies to the current session. The system then fails or succeeds the transaction depending on the rule and updates the instruction status accordingly.
For on-session card transactions, three main decision points are taken into account:
- When the user submits credit card details, they are validated. For example, the credit card is checked to see if it is listed in one of the pre-defined card testing scenarios listed below. If the details do not match, then a message displays stating, "Please enter a valid card number" and the user is required to enter a valid card number.
- Once the card details are accepted, the on-session flow is evaluated to have an outcome of DECLINED or AUTHORIZED.
- Once the transaction is authorized, the rules defined in the app are then applied to the transaction, and a COMPLETED or FAILED result is returned to the instruction. Depending on the rules, the financial instrument may be deactivated. For more information, see Financial Instrument Status below.
For DECLINED scenario outcomes, a DECLINED status is returned and the user is allowed to retry the transaction.
How to Configure Rules for Direct Debit and Credit Payment Methods
Before proceeding, follow Steps 1 through 3 in How to Install and Configure Apps.
Follow the steps below to configure the direct debit or credit payment method for testing.
- Select the desired direct debit or credit payment method by clicking the toggle switch next to its name. The button will appear.
- Click to add a rule to the payment method. Each rule defines the criteria for each scenario that will trigger a SUCCESS or FAILED result. The following fields will be presented:
| Field | Description |
|---|---|
| Order ref | Enter the order ID. |
| Instruction ref | Enter the instruction ID. |
| Customer ref | Enter the customer ID. |
| Amount From and to | Enter a range of amounts. |
| Result Status | Click to select SUCCESS or FAILED. |
| Error | This field is available only when Result Status is set to FAILED. Populate this field with the standard failed error code. This error code will be displayed in the Instruction Details as the errorCode. |
| Financial instrument details | Enter the key and value pair for the financial instrument you wish to test. For a complete list of available keys, see Financial Instrument Keys. Click to add another key and value pair. |
| Metadata | Enter the key and value for the instruction metadata you wish to test. Click to add another key and value pair. |
- Once the rule is defined, if you wish to define an additional rule, click .
- If you wish to define an additional payment method, return to Step 1.
- When all of the desired payment methods and associated rules have been defined, click to save the rules for the payment methods.
How to Configure Rules for Credit Card Payment Methods
Before proceeding, follow Steps 1 through 3 in How to Install and Configure Apps.
Follow the steps below to configure the credit card payment method for testing.
- Select the desired credit card payment method by clicking the toggle switch next to its name. The button will appear.
- Click to add a rule to the payment method. Each rule defines the criteria for each scenario that will trigger a SUCCESS or FAILED result. The following fields will be presented:
| Field | Description |
|---|---|
| Order ref | Enter the order ID. |
| Instruction ref | Enter the instruction ID. |
| Customer ref | Enter the customer ID. |
| Amount From and to | Enter a range of amounts. |
| Result Status | Click to select SUCCESS or FAILED. |
| Decline Code | This field is available only when the Result Status is set to FAILED. Click to select the journey for the instruction. |
| Financial instrument details | Enter the key and value pair for the financial instrument you wish to test. For a complete list of available keys, see Financial Instrument Keys. Click to add another key and value pair. |
| Metadata | Enter the key and value for the instruction metadata you wish to test. Click to add another key and value pair. |
- Once the rule is defined, if you wish to define an additional rule, click .
- If you wish to define an additional payment method, return to Step 1.
- When all of the desired payment methods and associated rules have been defined, click to save the rules for the payment methods.
Financial Instrument Keys
Each Financial Instrument has the following keys available.
BACS Direct Credit and Faster Payments
- FinancialInstrumentId
- accountHolderName
- accountNumber
- sortCode
BACS Direct Debit
- FinancialInstrumentId
- debtorName
- debtorAccountNumber
- debtorSortCode
Mastercard and Visa
- FinancialInstrumentId
- cardTokenBrand
- cardLast4Digits
- expiryMonth
- expiryYear
- cardHolderName
MB-WAY and M-Voucher
- FinancialInstrumentId
- MobileNumberCountryCode
- MobileNumber
SEPA Credit Transfer and SEPA Instant Credit
- FinancialInstrumentId
- name
- iban
- bic
SEPA Direct Debit Core
- FinancialInstrumentId
- debtorName
- debtorIban
- debtorBic
Card Testing Scenarios
Pre-defined scenarios are included in the testing app so that you can trigger different results by entering the following Card Numbers into the checkout session. For example, if a card with 3DS Enabled set to Yes is entered, the user will be prompted for a 3DS Challenge.
| Network | Card Number | Result | Declined Error Code | 3DS Enabled | FI Usage Type |
|---|---|---|---|---|---|
| Visa | 4000056655665555 | AUTHORIZED | n/a | Yes | Multiple |
| Mastercard | 5555555555551234 | AUTHORIZED | n/a | Yes | Multiple |
| Visa | 4000056655669876 | AUTHORIZED | n/a | No | Multiple |
| Mastercard | 5555555555559876 | AUTHORIZED | n/a | No | Multiple |
| Visa | 4000056655669999 | AUTHORIZED | n/a | Yes | Single |
| Mastercard | 5555555555554567 | AUTHORIZED | n/a | Yes | Single |
| Visa | 4000056655668888 | AUTHORIZED | n/a | No | Single |
| Mastercard | 5555555555556789 | AUTHORIZED | n/a | No | Single |
| Visa | 4000000000000001 | DECLINED | generic_decline | No | n/a |
| Mastercard | 5555555555550001 | DECLINED | generic_decline | No | n/a |
| Visa | 4000000000001111 | DECLINED | insufficient_funds | No | n/a |
| Mastercard | 5555555555551111 | DECLINED | insufficient_funds | No | n/a |
| Visa | 4000000000002222 | DECLINED | lost_card | No | n/a |
| Mastercard | 5555555555552222 | DECLINED | lost_card | No | n/a |
| Visa | 4000000000003333 | DECLINED | stolen_card | No | n/a |
| Mastercard | 5555555555553333 | DECLINED | stolen_card | No | n/a |
| Visa | 4000000000004444 | DECLINED | expired_card | No | n/a |
| Mastercard | 5555555555554444 | DECLINED | expired_card | No | n/a |
| Visa | 4000000000005555 | DECLINED | incorrect_cvc | No | n/a |
| Mastercard | 5555555555555555 | DECLINED | incorrect_cvc | No | n/a |
| Visa | 4000000000006666 | DECLINED | processing_error | No | n/a |
| Mastercard | 5555555555556666 | DECLINED | processing_error | No | n/a |
| Visa | 4000000000009999 | DECLINED | card_velocity_exceeded | No | n/a |
| Mastercard | 5555555555559999 | DECLINED | card_velocity_exceeded | No | n/a |
Financial Instrument Status
The resulting financial instrument status will be:
- ACTIVE when the the transaction has a SUCCESS result.
- When the transaction status is FAILED, then the system refers to the table below to assert the financial instrument status based on the declined code. If the declined code is not one of those listed below, it will fall back to INACTIVE.
| Error Code | FI Status |
|---|---|
| generic_decline | ACTIVE |
| insufficient_funds | ACTIVE |
| lost_card | INACTIVE |
| stolen_card | INACTIVE |
| card_velocity_exceeded | ACTIVE |
| expired_card | INACTIVE |
| incorrect_cvc | INACTIVE |
| processing_error | ACTIVE |
| incorrect_number | INACTIVE |
Troubleshooting
I have installed the wrong App and want to remove it.
You can't remove an installed App that you have referenced in an existing Collect Scheme or Payout Scheme. Payments will display an error message if you attempt to remove such Apps.
Uninstalling an App will remove all the information and configuration associated with the App.
If you have installed the wrong App, you can easily remove that App from the Installed apps page. Follow the steps below to remove an App.
- Go to Installed apps page.
- From the list of Installed apps, select that title of the App that you want to remove.
If you do not see the App you had installed, click the button next to the Search box. Then, on the App marketplace page click the Show Installed apps button to narrow down to the Apps you have installed.
- The App's setup page appears. Click on the Unistall App button on the top right corner of the page.
- A confirmation box will appear, prompting you to confirm your choice. Click Yes, uninstall.
- A slide-in banner on the top of the page will notify that the App has been removed successfully.
Payments didn't provide the information required to configure an App. Who should I talk to?
The information required to configure an App can only be provided by your PSP. Contact your PSP to get the information required to setup the App.
I can not see the App for my PSP.
Duck Creek is constantly adding Apps to support new PSPs. If you don't see the App associated with your PSP, reach out to your Account Manager to check if the App to support your PSP is currently in-development.
How can I see all the features an App supports.
There are two ways to see all the features an App supports.
- You can go to the App marketplace and click on the Learn more button next to the App you want to explore.
- You can go to the App's setup page and click on the App information button on the top right of the page.