Pay With Click Documentation

    Web Integration

    Checkout Flow

    The iframe code embeds the Click payment system into your website so you can take payments for goods and services without handling sensitive payment information such as credit card numbers.

    How To Install

    Before you start with the integration of the iframe you should create an account and sign up. Once your account is approved you will be able to log in to your account area and see your unique iframe code containing the {CUSTOMER_ID}.

    Copy the JavaScript code snippet provided into the HTML of your payment page and place it between the <body> tags where you would like the iframe to appear.

    <html>
  <body>
    Add the iframe code here
  </body>
</html>

    You should customise the parameters in the JavaScript snippet to set up your payment for a particular product or service.

    The success and failure URLs should present the customer with a message that the transaction has been completed or that it has failed and they have not been charged.

    Note:
    Settings of type string must be surrounded by either single or double quotes.

    Properties Summary
    Name Description
    currency string
    Default: "GBP".
    The currency used for this transaction
    Required
    amount decimal
    The value of this transaction. Positive number with two decimal places, no commas or thousand separators, no currency symbol
    Required
    reference string
    Your reference for this transaction
    Required
    container string
    Default: "ClickPayFrame".
    The id attribute of the HTML element which the iframe will be inserted into.
    Required
    successUrl string
    The URL a customer is taken to after a successful transaction. If a URL is blank, the customer will remain on the system and not be redirected.
    processingUrl string
    The URL a customer is taken to after a transaction is processing completion. This event may occur when there is a delay in the bank verifying and completiting/rejecting the transaction. If a URL is not entered, the customer will remain on the system and not be redirected.
    failureUrl string
    The URL a customer is taken to after a failed transaction. If a URL is blank, the customer will remain on the system and not be redirected.
    notificationUrl string
    The URL the payment system will automatically notify when this is a change in the status of the payment. Pleas see the payment notifications area for more information.
    width integer / string
    Default: "100%".
    The width of the iframe in pixels or percentage e.g. 100%
    height integer / string
    Default: 400. The height of the iframe in pixels or percentage e.g. 100%
    countryCodes Array of 2 digit country codes
    Filter the list of banks available to be selected by their 2 digit country codes e.g. ["GB", "FR", "DE"]
    recurringDay integer
    Valid values: 1 - 28
    Only used for recurring/repeat payments. Specify the day of the month when the repeated payment should take place.
    Note: this setting must be used along with numberOfRecurringPayments for recurring/repeatable payments to work.
    numberOfRecurringPayments integer
    Valid values: 1 - 28
    The number of recurring payments.
    Note: this setting must be used along with numberOfRecurringPayments for recurring/repeatable payments to work.
    Integration Sample
    					<html>
  <body>
    <script src="https://secure.pwclick.co.uk/embed.js?id={CUSTOMER_ID}"></script>
    <script>
      payWithClick({
        currency: 'GBP',
        amount: 25.00,
        countryCodes: ["GB"],
        reference: 'Custom reference code 1',
        container: 'ClickPayFrame',
        successUrl: 'https://www.domain.com/success',
        processingUrl: 'https://www.domain.com/processing',
        failureUrl: 'https://www.domain.com/failure',
        notificationUrl: 'https://www.domain.com/notify',
        width: '100%',
        height: 440,
        recurringDay: 1,
        numberOfRecurringPayments: 12
      });
    </script>
    <div id="ClickPayFrame"></div>
  </body>
</html>

     

     

    API

    Access

    All endpoints can be accessed via the following secure base URL:

    https://api.pwclick.co.uk/

    All requests must be made via HTTPS.

     

    Authentication

    Requests to the API are authenticated using your API Key and Secret. You can view and manage your API credentials in your customer area.

    Authentication is performed using HTTP Basic Authentication. Your API Key should be sent as the basic auth username and your API Secret should be sent as the basic auth password.

    HTTP Basic Authentication credentials are separated with a colon and base64 encoded, as follows:

    Base64Encode(Key + ':' + Secret)

     

    Endpoints

    Get Payments

    Used to retrieve a collection of stub payments records.

    Request

    GET 

    v1/payments

    This endpoint uses the following query string paramaters:

    Name Description
    from* string (date-time)
    Filter payments created from a specific date.
    Required
    to* string (date-time)
    Filter payments created up to a specific date.
    Required
    page integer
    (int32)
    The pagination page number.

    Responses

    Success - HTTP Status Code 200

    A successful collection of payments in JSON format. Pagination restricts 50 payments per page.

    Properties Summary
    Name Description
    totalResults integer
    The total number of results returned.
    page integer
    The current page.
    totalPages integer
    The total number of pages.
    pageSize integer
    The number of items returned in the results.
    results object
    A collection of payment (stub) response objects.
    JSON Sample
    {
  "totalResults": 2,
  "page": 1,
  "totalPages": 1,
  "pageSize": 50,
  "results": [
    {
      "id": 1,
      "reference": "123ABC",
      "status": "COMPLETED",
      "createdOn": "2022-10-05T14:14:09.915Z"
    },
    {
      "id": 2,
      "reference": "TCP-9999",
      "status": "PENDING",
      "createdOn": "2022-10-06T11:12:07.002Z"
    }
  ]
}

    Failure - HTTP Status Code 400

    Failed to correctly supply required parameters.

    Properties Summary
    Name Description
    statusCode integer
    The http status code of the error returned.
    message string
    The reason why the request failed.
    validationErrors object
    A collection of validation error response objects.
    JSON Sample
    {
  "statusCode": 400,
  "message": "Fields missing",
  "validationErrors": [
    {
      "field": "from",
      "message": "The from field is required and missing a value."
    }
  ]
}

    Failure - HTTP Status Code 401

    Unauthorised to view payments.

    Properties Summary
    Name Description
    statusCode integer
    The http status code of the error returned.
    message string
    The reason why the request failed.
    JSON Sample
    {
  "statusCode": 401,
  "message": "You are not authorised to view this payment."
}

     

    Get Payment

    Used to retrieve a single detailed payment record.

    Request

    GET 

    v1/payments/{id}

    This endpoint uses the following paramaters:

    Name Description
    id* ineteger
    The id of the payment.
    Required

    Responses

    Success - HTTP Status Code 200

    A detailed payment record.

    Properties Summary
    Name Description
    id integer
    The id of the payment.
    reference string
    The reference of the payment.
    status string
    The status of the payment. Valid statuses are Pending, Completed, Failed, Cancelled.
    institutionName string
    The name of the institution used for the payment.
    currencyCode string
    The currency code (ISO 4217) of the payment.
    amount decimal
    The amount of the payment.
    successUrl string
    The URL a customer is taken to after a successful transaction.
    failureUrl string
    The URL a customer is taken to after a failed transaction.
    completedOn string (date-time)
    The date and time of when the payment was completed.
    createdOn string (date-time)
    The date and time of when the payment was created.
    failureLogs object
    A collection of failure logs objects for this payment.
    JSON Sample
    {
  "id": 234234,
  "reference": "TCP-12345666",
  "status": "Failed",
  "institutionName": "Nationwide",
  "currencyCode": "GBP",
  "amount": 23.99,
  "successUrl": "https://www.domain.com/success",
  "failureUrl": "https://www.domain.com/failure",
  "completedOn": "2022-10-05T14:44:10.331Z",
  "createdOn": "2022-10-05T14:40:12.332Z",
  "failureLogs": [
    {
      "type": "PAYMENT",
      "source": "Yapily",
      "code": "400",
      "status": "BAD_REQUEST",
      "message": "The IBAN number used is not valid. ",
      "tracingId": "5f86a924fbbd407493d303b25a936a06",
      "createdOn": "2022-10-05T14:40:12.332Z"
    }
  ]
}

    Failure - HTTP Status Code 400

    Failed to correctly supply required parameters.

    Properties Summary
    Name Description
    statusCode integer
    The http status code of the error returned.
    message string
    The reason why the request failed.
    validationErrors object
    A collection of validation error response objects.
    JSON Sample
    {
  "statusCode": 400,
  "message": "Fields missing",
  "validationErrors": [
    {
      "field": "from",
      "message": "The from field is required and missing a value."
    }
  ]
}

    Failure - HTTP Status Code 401

    Unauthorised to view payment.

    Properties Summary
    Name Description
    statusCode integer
    The http status code of the error returned.
    message string
    The reason why the request failed.
    JSON Sample
    {
  "statusCode": 401,
  "message": "You are not authorised to view this payment."
}

    Failure - HTTP Status Code 404

    Payment not found.

    Properties Summary
    Name Description
    statusCode integer
    The http status code of the error returned.
    message string
    The reason why the request failed.
    JSON Sample
    {
  "statusCode": 401,
  "message": "You are not authorised to view this payment."
}

     

     

    Webhooks

    Payment Notifications

    The payment notifications service allows for our system to send a message to a specified notification URL with the latest status of the payment. This service can be used to keep track of completed payment transactions.

    To enable the payment notification service, please login to the CRM and enable the payment notifications option. You must also enter a notification URL for the status to be sent to.

    Our system will attempt to periodically re-send any notifications that do not return a successful http status code (200) from your notification URL.

    Note: The notification url must use a secure connection (https://).

    Request

    When a payment's status has been updated e.g. Cancelled, Completed, our system will POST a JSON request body to the notification URL containing the following information:

    POST 

    e.g. https://www.yourdomain.com/notifications

    Properties Summary
    Name Description
    id integer
    The id of the payment transaction.
    reference string
    The payment reference code.
    status string
    The status of the payment. Valid statuses are Pending, Completed, Failed, Cancelled.
    institutionName string
    The name of the institution used for the payment.
    currencyCode string
    The currency code (ISO 4217) of the payment.
    amount decimal
    The amount of the payment.
    completedOn string (date-time)
    The date and time of when the payment was completed.
    createdOn string (date-time)
    The date and time of when the payment was created.
    JSON Request Sample
    {
	"id": 5000,
	"reference": "Example Payment 1",
	"currencyCode": "GBP",
	"amount": 9.99,
	"status": "Completed",
	"institutionName": "Natwest",
	"createdOn": "2022-02-22T12:00:32",
	"lastUpdatedOn": "2022-02-22T12:02:25"
}

    Validate Payment Notification

    To validate the origin and authenticity of the notification, POST back the original JSON request body to https://secure.pwclick.co.uk/notifications/validate. This service will check and validate to see if the payment notification originated from our system which can help you prevent fraudalent external updates.

    Request

    POST 

    https://secure.pwclick.co.uk/notifications/validate

    Example cURL Request

    curl --location --request POST 'https://secure.pwclick.co.uk/notifications/validate' \
--header 'Content-Type: application/json' \
--data-raw '{"id":1234,"reference":"Test 1","currencyCode":"GBP","amount":9.999,"status":"Completed","institutionName":"Nationwide","createdOn":"2022-02-21T16:02:36","lastUpdatedOn":"2022-02-21T16:06:11"}'

    Response

    Success - HTTP Status Code 200

    An example of a successful and valid response:

    Properties Summary
    Name Description
    valid boolean
    A boolean value (true/false) representing if the notification request has validated successfully.
    JSON Sample
    {
	"valid": true
}

    Failure - HTTP Status Code 200

    An example of a successful and valid response:

    Properties Summary
    Name Description
    valid boolean
    A boolean value (true/false) representing if the notification request has validated successfully.
    JSON Sample
    {
	"valid": false
}

    Inbound Bank Payment Notifications

    Our system is setup to receive external payment updates.

    Note: Inbound bank payment notifications are subject to verification and require the sender's IP address to be whitelisted. IP's can be added to the whitelist via your CRM login.

    Request

    To notify our system of a payment update, you can POST the following request:

    POST 

    https://secure.pwclick.co.uk/notifications/receive

    Properties Summary
    Name Description
    id integer
    The id of the PWClick payment transaction.
    reference string
    The PWClick payment reference code.
    status string
    The status of the payment. Valid statuses are Pending, Awaiting Authorisation, Completed, Failed, Cancelled.
    institutionName string
    The name of the institution used for the payment.
    currencyCode string
    The currency code (ISO 4217) of the payment.
    amount decimal
    The amount of the payment.
    completedOnUtc string (date-time)
    The UTC date and time of when the payment was completed.
    createdOnUtc string (date-time)
    The UTC date and time of when the payment was created.
    JSON Request Sample
    {
	"id": 5000,
	"reference": "Example Payment 1",
	"currencyCode": "GBP",
	"amount": 9.99,
	"status": "Completed",
	"institutionName": "Natwest",
	"createdOnUtc": "2022-02-22T12:00:32",
	"completedOnUtc": "2022-02-22T12:02:25"
}

    Success - HTTP Status Code 200

    If the payment notification is valid and has successfully entered our system:

    JSON Sample
    {
	true
}

    Failure - HTTP Status Code 200

    If the payment notification is valid but has not successfully entered our system:

    JSON Sample
    {
	true
}

    Failure - HTTP Status Code 400

    If the request does not match the specification, a 400 HTTP code status will be returned.

    Properties Summary
    Name Description
    statusCode integer
    The http status code of the error returned.
    message string
    The reason why the request failed.
    validationErrors object
    A collection of validation error response objects.
    JSON Sample
    {
  "statusCode": 400,
  "message": "Fields missing",
  "validationErrors": [
    {
      "field": "from",
      "message": "The from field is required and missing a value."
    }
  ]
}

    Failure - HTTP Status Code 401

    If you are unauthorised to send notifications to our system, a 401 HTTP code status will be returned.

    Properties Summary
    Name Description
    statusCode integer
    The http status code of the error returned.
    message string
    The reason why the request failed.
    JSON Sample
    {
  "statusCode": 401,
  "message": "You are not authorised to view this payment."
}

    Failure - HTTP Status Code 404

    If the payment can not be found in our system, a 404 HTTP code status will be returned.

    Properties Summary
    Name Description
    statusCode integer
    The http status code of the error returned.
    message string
    The reason why the request failed.
    JSON Sample
    {
  "statusCode": 404,
  "message": "The record was not found."
}

     

     

    Model Glossary

    Payments Response

    Properties Summary
    Name Description
    totalResults integer
    The total number of results returned.
    page integer
    The current page.
    totalPages integer
    The total number of pages.
    pageSize integer
    The number of items returned in the results.
    results object
    A collection of payment (stub) response objects.
    JSON Sample
    {
  "totalResults": 2,
  "page": 1,
  "totalPages": 1,
  "pageSize": 50,
  "results": [
    {
      "id": 1,
      "reference": "123ABC",
      "status": "COMPLETED",
      "createdOn": "2022-10-05T14:14:09.915Z"
    },
    {
      "id": 2,
      "reference": "TCP-9999",
      "status": "PENDING",
      "createdOn": "2022-10-06T11:12:07.002Z"
    }
  ]
}

    Payment (Stub) Response

    Properties Summary
    Name Description
    id integer
    The id of the payment.
    reference string
    The reference of the payment.
    status string
    The status of the payment. Valid statuses are Pending, Completed, Failed, Cancelled.
    createdOn string (date-time)
    The date and time of when the payment was created.
    JSON Sample
    {
	"id": 1,
	"reference": "ABC123",
	"status": "COMPLETED",
	"createdOn": "2022-10-05T14:40:12.325Z"
}

    Payment (Detailed) Response

    Properties Summary
    Name Description
    id integer
    The id of the payment.
    reference string
    The reference of the payment.
    status string
    The status of the payment. Valid statuses are Pending, Completed, Failed, Cancelled.
    institutionName string
    The name of the institution used for the payment.
    currencyCode string
    The currency code (ISO 4217) of the payment.
    amount decimal
    The amount of the payment.
    successUrl string
    The URL a customer is taken to after a successful transaction.
    failureUrl string
    The URL a customer is taken to after a failed transaction.
    completedOn string (date-time)
    The date and time of when the payment was completed.
    createdOn string (date-time)
    The date and time of when the payment was created.
    failureLogs object
    A collection of failure logs objects for this payment.
    JSON Sample
    {
  "id": 234234,
  "reference": "TCP-12345666",
  "status": "Failed",
  "institutionName": "Nationwide",
  "currencyCode": "GBP",
  "amount": 23.99,
  "successUrl": "https://www.domain.com/success",
  "failureUrl": "https://www.domain.com/failure",
  "completedOn": "2022-10-05T14:44:10.331Z",
  "createdOn": "2022-10-05T14:40:12.332Z",
  "failureLogs": [
    {
      "type": "PAYMENT",
      "source": "Yapily",
      "code": "400",
      "status": "BAD_REQUEST",
      "message": "The IBAN number used is not valid. ",
      "tracingId": "5f86a924fbbd407493d303b25a936a06",
      "createdOn": "2022-10-05T14:40:12.332Z"
    }
  ]
}

    Failure Log Response

    Properties Summary
    Name Description
    type string
    The type of failure.
    source string
    The source of the failure.
    code string
    The source's code of the failure.
    status string
    The source's status of the failure.
    message string
    The source's message of the failure.
    tracingId string
    The source's tracing id of the failure.
    createdOn string (date-time)
    The date and time the failure was logged.
    JSON Sample
    {
	"type": "PAYMENT",
	"source": "Yapily",
	"code": "400",
	"status": "BAD_REQUEST",
	"message": "The IBAN number used is not valid. ",
	"tracingId": "5f86a924fbbd407493d303b25a936a06",
	"createdOn": "2022-10-05T14:40:12.332Z"
}

    Error Bad Request Response

    Properties Summary
    Name Description
    statusCode integer
    The http status code of the error returned.
    message string
    The reason why the request failed.
    validationErrors object
    A collection of validation error response objects.
    JSON Sample
    {
  "statusCode": 400,
  "message": "Fields missing",
  "validationErrors": [
    {
      "field": "from",
      "message": "The from field is required and missing a value."
    }
  ]
}

    Error Response

    Properties Summary
    Name Description
    statusCode integer
    The http status code of the error returned.
    message string
    The reason why the request failed.
    JSON Sample
    {
  "statusCode": 401,
  "message": "You are not authorised to view this payment."
}

    Error Not Found Response

    Properties Summary
    Name Description
    statusCode integer
    The http status code of the error returned.
    message string
    The reason why the request failed.
    JSON Sample
    {
  "statusCode": 404,
  "message": "The record was not found."
}

    Validation Error Response

    Properties Summary
    Name Description
    field string
    The name of the field associated with the error.
    message string
    The reason for the error.
    JSON Sample
    {
  "field": "from",
  "message": "The from field is required and missing a value."
}