Products
Our Platform
Developers
Sectors
Pricing
Developers
Try it out
Contact
About

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="https://sdk.citizen.is/sdk/payment-sdk.js"></script>

Step 2

Initialise the SDK

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


<script>
	window.citizenAsyncInit = function () {
  CITIZEN_PAYMENT.init({
  	publicApiKey: '[Your-entity-public-api-key]'
    })
  };
</script>

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.setCustomerEmailAddress(DB.getCustomerEmail);
	    citizenPaymentDetails.setmerchantEmailAddress("info@company.com");//should be the same as your entity.
	    citizenPaymentDetails.setAmount(details.getAmount);
	    citizenPaymentDetails.setCurrency("USD");
	    citizenPaymentDetails.setShortReference("MyShortReference123");
	    citizenPaymentDetails.setDetailedReference("This is my detailed reference");
	    citizenPaymentDetails.setCustomerIP(details.getIPAddress());//should be IPv4
	    citizenPaymentDetails.setCustomerDeviceOs(details.getOS());

	    RestTemplate restTemplate = new RestTemplate();

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

	    ResponseEntity<TextNode> paymentInitResponse = restTemplate
	    .exchange("https://api.citizen.is/v1/tokens/payment-email-init", 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.


<script>
//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.
  });
</script>