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:

• Go
• Git
• MongoDB

Getting Started

1. Clone this repository: go get github.com/companieshouse/payments.api.ch.gov.uk
2. 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:

1. export SSH_PRIVATE_KEY_PASSPHRASE='[your SSH key passhprase goes here]' (optional, set only if SSH key is passphrase protected)
2. 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 .