Companies House Payments API

The Companies House API for handling payments.

Requirements

In order to run this API locally you will need to install the following:

Getting Started

Clone this repository: go get github.com/companieshouse/payments.api.ch.gov.uk
Build the executable: make build

Configuration

Variable	Default	Description
`BIND_ADDR`		Payments API Port
`MONGODB_URL`		MongoDB URL
`MONGODB_DATABASE`	`payments`	MongoDB database name
`MONGODB_COLLECTION`	`payments`	MongoDB collection name
`DOMAIN_ALLOW_LIST`		List of valid domains for the Resource URL
`PAYMENTS_WEB_URL`		URL for the Payments Web service
`PAYMENTS_API_URL`		URL for the Payments API
`GOV_PAY_URL`		URL for GOV.UK Pay
`GOV_PAY_BEARER_TOKEN_TREASURY`		Treasury Bearer Token for GOV.UK Pay
`GOV_PAY_BEARER_TOKEN_CH_ACCOUNT`		CH Accont Bearer Token for GOV.UK Pay
`GOV_PAY_BEARER_TOKEN_LEGACY`		Legacy Service Bearer Token for GOV.UK Pay
`EXPIRY_TIME_IN_MINUTES`		Number of minutes before a payment session expires
`KAFKA_BROKER_ADDR`		Kafka Broker address
`SCHEMA_REGISTRY_URL`		Schema Registry URL
`CHS_API_KEY`		API access key
`SECURE_APP_COSTS_REGEX`		Regex to match secure app costs resource
`PAYPAL_ENV`		live or test
`PAYPAL_CLIENT_ID`		PayPal Client ID
`PAYPAL_SECRET`		Paypal Secret

Endpoints

Method	Path	Description
GET	/healthcheck	Checks the health of the service
POST	/payments	Create Payment Session
GET	/payments/{payment_id}	Get Payment Session
POST	/payments/{payment_id}/refunds	Create Refund
PATCH	/private/payments/{payment_id}	Patch Payment Session
POST	/private/payments/{payment_id}/external-journey	Returns URL for external Payment Provider
GET	/callback/payments/govpay/{payment_id}	GOV.UK Pay callback
GET	/callback/payments/paypal/orders/{payment_id}	PayPal callback

The Create Payment Session POST endpoint receives a body in the following format:

{
    "redirect_uri": "string",
    "reference": "string",
    "resource": "string",
    "state": "string"
}

and returns a Payment Resource in the response:

{
    "amount": "string",
    "available_payment_methods": [
        "string"
    ],
    "completed_at": "date-time",
    "created_at": "date-time",
    "created_by": {
        "email": "string",
        "forename": "string",
        "id": "string",
        "surname": "string"
    },
    "description": "string",
    "links": {
        "journey": "string",
        "resource": "string",
        "self": "string"
    },
    "payment_method": "string",
    "reference": "string",
    "status": "string"
}

The Create Refund POST endpoint receives a body in the following format:

{
    "amount": 800
}

and returns a Refund Resource in the response:

{
    "refund_id": "string",
    "created_date_time": "string",
    "amount": 800,
    "status": "string"
}

External Payment Providers

The external payment providers currently supported are GOV.UK Pay and PayPal.

A summary/Choose payment method screen is shown depending on what allowed_payment_methods are set as part of the GET payment details endpoint.

Returning to the payments Service

Docker support

Pull image from private CH registry by running docker pull 169942020521.dkr.ecr.eu-west-1.amazonaws.com/local/payments.api.ch.gov.uk:latest command or run the following steps to build image locally:

export SSH_PRIVATE_KEY_PASSPHRASE='[your SSH key passhprase goes here]' (optional, set only if SSH key is passphrase protected)
DOCKER_BUILDKIT=0 docker build --build-arg SSH_PRIVATE_KEY="$(cat ~/.ssh/id_rsa)" --build-arg SSH_PRIVATE_KEY_PASSPHRASE -t 169942020521.dkr.ecr.eu-west-1.amazonaws.com/local/payments.api.ch.gov.uk:latest .

companieshouse/payments.api.ch.gov.uk