Our Platform
Try it out

Integrate Account Holder Confirmation

Body lorem Ipsum

Try it out

This will make a real payment of £1.
All money we receive will be donated to XXXXX charity.

Step 1

Add our SDK

Add our payment SDK to the HTML header of your web page

<script src=""></script>

Step 2

Initialise the SDK

Using your registered account, initialise the SDK with your entity API key.

	window.citizenAsyncInit = function () {
  	publicApiKey: '[Your-entity-public-api-key]'

Step 3

Create a payment

On your server, you can initialise a payment using a simple API call. This creates a payment transaction ID you pass to your front end.

    public class CitizenTransactionDetails implements Serializable {
    // This is just a Java class that represents the json object that you will need to send to the citizen backend.
    // These are required fields.
    private static final long serialVersionUID = 2018243255361847281L;

    private String paymentGiro; //Either FPS or SEPA
    private String customerEmailAddress;
    private String merchantEmailAddress;
    private String amount;
    private String currency; // has to be a valid currency ISO code e.g. USD, EUR, GBP
    private String shortReference;
    private String detailedReference;
    private String customerIpAddress;
    private String customerDeviceOs;

    //Getters and Setters

    //Your backend will then make a request to the Citizen service to create a transaction.
    @RequestMapping(method = RequestMethod.POST, path = "/your-example-payment-endpoint")
    public Callable<ResponseEntity<TextNode>> createCitizenPaymentTransaction(TransactionDetails details) {

	    CitizenTransactionDetails citizenPaymentDetails = new CitizenTransactionDetails();
	    citizenPaymentDetails.setmerchantEmailAddress("");//should be the same as your entity.
	    citizenPaymentDetails.setDetailedReference("This is my detailed reference");
	    citizenPaymentDetails.setCustomerIP(details.getIPAddress());//should be IPv4

	    RestTemplate restTemplate = new RestTemplate();

	    HttpHeaders httpHeaders = new HttpHeaders();
	    httpHeaders.set("AuthorizationCitizen", [YOUR_ENTITY_API_KEY]]);

	    ResponseEntity<TextNode> paymentInitResponse = restTemplate
	    .exchange("", HttpMethod.POST,
	    new HttpEntity<>(citizenPaymentDetails, httpHeaders), TextNode.class);

	    String citizenPaymentTransactionId = paymentInitResponse.getBody().asText();

	    return ResponseEntity.ok(new TextNode(citizenPaymentTransactionId)); //Return this to your front end

Step 4

Start payment journey

Once you have your Citizen payment transaction ID you can use it with our SDK to start the payment journey.

//citizenPaymentTransactionId - from the previous step
//citizenPaymentCallback - You can pass in a callback which is called when the journey is completed
//options - (optional) a set of options you want to run when starting the payment journey

let citizenPaymentCallback = (response) => {
  if (response.getPaymentStatus === 'SUCCESS') {
    window.location.replace('to success screen')
    } else {
    window.location.replace('to failure screen')
window.CITIZEN_PAYMENT.startPaymentJourney(citizenPaymentTransactionId, citizenPaymentCallback, {
  userEmail: [customer's email] //this will be shown on the payment modal, otherwise a generic message will be shown.