The Payments Connector in Java (Dropwizard)
Switch branches/tags
testing_tag_release-2 testing_tag_release-1 approved-alpha_staging-6 approved-alpha_staging-5 approved-alpha_staging-1-65 approved-alpha_staging-1-64 approved-alpha_staging-1-63 approved-alpha_staging-1-59 approved-alpha_staging-1-57 approved-alpha_staging-1-49 approved-alpha_staging-1-48 approved-alpha_staging-1-47 approved-alpha_staging-1-46 approved-alpha_staging-1-45 approved-alpha_staging-1-44 approved-alpha_staging-1-43 approved-alpha_staging-1-41 approved-alpha_staging-1-40 approved-alpha_staging-1-39 approved-alpha_staging-0-26 approved-alpha_staging-0-16 approved-alpha_staging-0-14 approved-alpha_staging-0-7 approved-alpha_release-174 approved-alpha_release-172 approved-alpha_release-170 approved-alpha_release-168 approved-alpha_release-167 approved-alpha_release-166 approved-alpha_release-165 approved-alpha_release-163 approved-alpha_release-162 approved-alpha_release-161 approved-alpha_release-160 approved-alpha_release-158 approved-alpha_release-157 approved-alpha_release-156 approved-alpha_release-155 approved-alpha_release-154 approved-alpha_release-153 approved-alpha_release-151 approved-alpha_release-150 approved-alpha_release-149 approved-alpha_release-147 approved-alpha_release-146 approved-alpha_release-145 approved-alpha_release-144 approved-alpha_release-143 approved-alpha_release-141 approved-alpha_release-140 approved-alpha_release-139 approved-alpha_release-138 approved-alpha_release-137 approved-alpha_release-135 approved-alpha_release-134 approved-alpha_release-132 approved-alpha_release-131 approved-alpha_release-130 approved-alpha_release-128 approved-alpha_release-127 approved-alpha_release-126 approved-alpha_release-125 approved-alpha_release-124 approved-alpha_release-123 approved-alpha_release-121 approved-alpha_release-120 approved-alpha_release-119 approved-alpha_release-118 approved-alpha_release-117 approved-alpha_release-116 approved-alpha_release-115 approved-alpha_release-114 approved-alpha_release-113 approved-alpha_release-111 approved-alpha_release-109 approved-alpha_release-108 approved-alpha_release-106 approved-alpha_release-105 approved-alpha_release-104 approved-alpha_release-103 approved-alpha_release-102 approved-alpha_release-101 approved-alpha_release-100 approved-alpha_release-99 approved-alpha_release-98 approved-alpha_release-97 approved-alpha_release-96 approved-alpha_release-95 approved-alpha_release-94 approved-alpha_release-93 approved-alpha_release-92 approved-alpha_release-91 approved-alpha_release-90 approved-alpha_release-89 approved-alpha_release-88 approved-alpha_release-87 approved-alpha_release-86 approved-alpha_release-85 approved-alpha_release-84 approved-alpha_release-83
Nothing to show
Clone or download
oswaldquek Merge pull request #737 from alphagov/PP-4276
PP-4276: Use direct debit connector's DropwizardJUnitRunner
Latest commit 7393e94 Oct 19, 2018


The GOV.UK Pay Connector in Java (Dropwizard)

Environment Variables

Varible Default Purpose
AUTH_READ_TIMEOUT_SECONDS 10 seconds the timeout before the resource responds with an awaited auth response (202), so that frontend can choose to show a spinner and poll for auth response. Supports any duration parsable by dropwizard Duration
SECURE_WORLDPAY_NOTIFICATION_ENABLED false whether to filter incoming notifications by domain; they will be rejected with a 403 unless they match the required domain
SECURE_WORLDPAY_NOTIFICATION_DOMAIN incoming requests will have a reverse DNS lookup done on their domain. They must resolve to a domain with this suffix (see DnsUtils.ipMatchesDomain())
NOTIFY_EMAIL_ENABLED false Whether confirmation emails will be sent using GOV.UK Notify
NOTIFY_PAYMENT_RECEIPT_EMAIL_TEMPLATE_ID - ID of the email template specified in the GOV.UK Notify to be used for sending emails. An email template can accept personalisation (placeholder values which are passed in by the code).
NOTIFY_API_KEY - API Key for the account created at GOV.UK Notify
NOTIFY_BASE_URL Base URL of GOV.UK Notify API to be used
GDS_CONNECTOR_WORLDPAY_TEST_URL - Pointing to the TEST gateway URL of Worldpay payment provider.
GDS_CONNECTOR_WORLDPAY_LIVE_URL - Pointing to the LIVE gateway URL of Worldpay payment provider.
GDS_CONNECTOR_SMARTPAY_TEST_URL - Pointing to the TEST gateway URL of Smartpay payment provider.
GDS_CONNECTOR_SMARTPAY_LIVE_URL - Pointing to the LIVE gateway URL of Smartpay payment provider.
GDS_CONNECTOR_EPDQ_TEST_URL - Pointing to the TEST gateway URL of ePDQ payment provider.
GDS_CONNECTOR_EPDQ_LIVE_URL - Pointing to the LIVE gateway URL of ePDQ payment provider.
ASYNCHRONOUS_CAPTURE true whether to handle capture asynchronously. When asynchronous capture is enabled, capture requests are deferred and operated in batch by a background task

Background captures

The background capture mechanism will capture all payments in the CAPTURE_APPROVED state.

A background thread managed by dropwizard runs on all connector nodes. It polls the database periodically to check for payments which need to be captured.

The polling interval is a random value between 150-200 seconds.

If a capture attempt fails it will be retried again after a specified delay (CAPTURE_PROCESS_RETRY_FAILURES_EVERY).

The following variables control the background process:

Varible Default Purpose
CAPTURE_PROCESS_BATCH_SIZE 10 limits the batch window size processed at each polling attempt. If connector is not managing to clear the queue of captures, increase this value.
CAPTURE_PROCESS_RETRY_FAILURES_EVERY 60 minutes a failed capture attempt will be returned to the queue, and will not be retried until this time has passed
CAPTURE_PROCESS_MAXIMUM_RETRIES 48 connector keeps track of the number of times capture has been attempted for each charge. If a charge fails this number of times or more it will be marked as a permanent failure. An error log message will be written as well. This should never happen and if it does it should be investigated.

Integration tests

To run the integration tests, the DOCKER_HOST and DOCKER_CERT_PATH environment variables must be set up correctly. On OS X the environment can be set up with:

Contract tests

$GDS_CONNECTOR_WORLDPAY_PASSWORD and$GDS_CONNECTOR_WORLDPAY_PASSWORD environment variable must be set for Worldpay contract tests. GDS_CONNECTOR_SMARTPAY_USER, GDS_CONNECTOR_SMARTPAY_PASSWORD must be set for the smartpay contract tests.

    eval $(boot2docker shellinit)
    eval $(docker-machine env <virtual-machine-name>)

The command to run all the tests is:

    mvn test

API Specification

The API Specification provides more detail on the paths and operations including examples.

Tasks namespace

Path Supported Methods Description
/v1/tasks/expired-charges-sweep POST Spawns a task to expire charges with a default window of 90 minutes

Command line tasks

There are a number of commands which can run from the command line. Invoke the all-in-one jar to see a list of the commands:

$ java -jar target/pay-connector-0.1-SNAPSHOT-allinone.jar
  • waitOnDependencies [-h] [file] - Waits for dependent resources to become available

    positional arguments: file - application configuration file

  • render-state-transition-graph - Outputs a representation of the connector state transitions as a graphviz 'dot' file

API namespace

Path Supported Methods Description
/v1/api/accounts POST Create a new account to associate charges with
/v1/api/accounts GET Retrieves a collection of all the accounts
/v1/api/accounts/{gatewayAccountId} GET Retrieves an existing account without the provider credentials
/v1/api/accounts/{accountId}/charges/{chargeId} GET Returns the charge with chargeId belongs to account accountId
/v1/api/accounts/{accountId}/charges POST Create a new charge for this account accountId
/v1/api/accounts/{accountId}/charges GET Searches transactions for this account accountId returns JSON or CSV as requested
/v1/api/notifications/worldpay POST Handle charge update notifications from Worldpay.
/v1/api/notifications/smartpay POST Handle charge update notifications from Smartpay.
/v1/api/notifications/epdq POST Handle charge update notifications from ePDQ.
/v1/api/accounts/{accountId}/charges/{chargeId}/cancel POST Cancels the charge with chargeId for account accountId
/v1/api/accounts/{accountId}/charges/{chargeId}/events GET Retrieves all the transaction history for the given chargeId of account accountId
/v1/api/accounts/{accountId}/email-notification PATCH Changes settings for email notifications for the given account accountId
/v1/api/accounts/{accountId}/description-analytics-id PATCH Allows editing description and/or analyticsId for the given account accountId
/v1/api/accounts/{accountId}/charges/{chargeId}/refunds POST Submits a refund for a given charge chargeId and a given accountId
/v1/api/accounts/{accountId}/charges/{chargeId}/refunds GET Retrieves all refunds associated to a charge chargeId and a given accountId
/v1/api/accounts/{accountId}/charges/{chargeId}/refunds/{refundId} GET Retrieves a refund by refundId for a given charge chargeId and a given accountId
/v1/api/accounts/{accountId}/transactions-summary GET Retrieves payment summary totals for a given accountId
/v1/api/reports/performance-report GET Retrieves performance summary
/v1/api/reports/gateway-account-performance-report GET Retrieves performance summary segmented by gateway account
/v1/api/reports/daily-performance-report GET Retrieves performance summary for a given day

Frontend namespace

Path Supported Methods Description
/v1/frontend/accounts/{accountId} GET Retrieves an existing account together with the provider credentials
/v1/frontend/accounts/{accountId} PUT Update gateway credentials associated with this account
/v1/frontend/charges/{chargeId}/status PUT Update status of the charge
/v1/frontend/charges/{chargeId} GET Find out the status of a charge
/v1/frontend/charges/{chargeId}/cards POST Authorise the charge with the card details
/v1/frontend/charges/{chargeId}/capture POST Confirm a card charge that was previously authorised successfully.
/v1/frontend/charges?gatewayAccountId={gatewayAccountId} GET List all transactions for a gateway account
/v1/frontend/tokens/{chargeTokenId}/charge GET Retrieve information about a secure redirect token.
/v1/frontend/tokens/{chargeTokenId} DELETE Delete the secure redirect token.


MIT License

Responsible Disclosure

GOV.UK Pay aims to stay secure for everyone. If you are a security researcher and have discovered a security vulnerability in this code, we appreciate your help in disclosing it to us in a responsible manner. We will give appropriate credit to those reporting confirmed issues. Please e-mail with details of any issue you find, we aim to reply quickly.