Products
Developers
Sectors
Blog
About

Integrate Payments

Get up and running with fast, low-cost account-to-account payments today

Try it out

This will make a real payment of £1.
All money we receive will be donated to help those effected by the Australian bush fires.

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>

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>

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
	    }  
	}

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>