1. Add our sign-in SDK to the html header of your webpage.
<script src="https://sdk.citizen.is/sdk/payment-sdk.js"/>
2. Initialise the Citizen Payment SDK
<script>
window.citizenAsyncInit = function () {
CITIZEN_PAYMENT.init({
publicApiKey: '[Your-entity-public-api-key]'
})
};
</script>
3. You will need to initially create a payment transaction. This will be done on the server side
Below is a Java springboot example:
//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.
public class CitizenTransactionDetails implements Serializable {
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
}
4. Once you have your citizen payment transaction Id you can use it with our Payment 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) => {
console.log("our response: " + 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>