2. 1 | P a g e
Implementing Online Payments with RESTful API
Introduction ......................................................................................................2
Creating a Payment Token ...............................................................................3
Step.1 .............................................................................................................3-4
Inserting Our JavaScript Code into your Web Page …………………………………………5
Step 2 .............................................................................................................5-6
The customer’s card charged and the confirmation to your server displayed….7
Step.3 ...............................................................................................................7
Verification of the payment token…………………………………………………………………8
Step.4 ..........................................................................................................8-12
Appendix .........................................................................................................13
Company’s name.js ........................................................................................13
API Keys ..........................................................................................................14
3. 2 | P a g e
Implementing (company’s name) Online Payment System using Java and
JavaScript RESTful API
Introduction
This is a developer’s guide which gives the developer an Open Source instructional steps on how- to
implement (company’s name) online payment system, using Java and JavaScript API. The online
payment developer’s guide will allow the developer to embed (company’s name) online payment
system into the merchant’s website(s).
The developer will need to firstly, integrate the payment methods into the website and then he will
incorporate forms, customers’ inputs and payment charge validations from the customer’s credit or
debit card, over a secure payment process.
The developer will also have access to our server through the web browser and request for a payment
token transaction resource. Our server will then respond back to the developer, by asking for the
requested Content-Type and the merchant’s API key (this was given to the merchant when the
merchant’s account was created). The payment request and response with our server and the
developer will then take place.
Once the developer has implemented the requested customer’s payments and information in
JavaScript. The developer would need to implement the response to the request of the customer’s
payment. This request will be pending in the merchant’s server awaiting the server’s response. The
implementation of this response to the customer is done in Java. The developer would then
implement the verification to the payment token from the customer and, the charge will be processed
giving an authentication access to all available resources.
4. 3 | P a g e
Creating a Payment Token
Before the developer can implement the request from the customer, he will now need to access our
server from the web browser.
Step 1. Open a new browser.
Type the following URL:
http://sandbox.(company’s).com/api2/v2/tokens/payment
This URL will now action the Sandbox server at (company’s name) mapping all the data the developer
will need to setup tokens and payments transactions. This URL also allows the server to POST all the
information in the body of the Sandbox.
(company’s).com/api2/v2/tokens/payment
From this point in the URL this triggers of the server. The developer is now in the position to exchange
information about the payment token transactions’ resources with the server. This is done through
the HTTP:// protocol known as the web browser.
Once you have requested for the payment token resource through the HTTP:// web browser. The
server will respond back asking the developer to specify the Content-Type. This response is done
through header.
In the Header:
Include the following:
Content-Type: application/json;
Authorisation: 'sk_093F4C8D-E608-4B8D-9B39-8C2491345864'
The application is in JSON tailored for developers who wish to use a web browser (client-side), this is
defined by the Content-Type: application/json; .
The Authorisation: 'sk_093F4C8D-E608-4B8D-9B39-8C2491345864' is where the authorisation is the
API public. It was given to the merchant when the account was created.
5. 4 | P a g e
The developer can REQUEST in the URL the payment amount and currency in pounds sterling.
{
"value": 100,
"currency": "GBP"
}
The server will then RESPOND with the customer’s payment token
{
"id": "pay-tok_SPECIMEN-000",
}
Note: the Header contain the Metadata of the API private or public key needed for authorisation.
6. 5 | P a g e
Inserting Our JavaScript Code into the merchant’s Web Page
The developer can now access the merchant’s website and insert the following JavaScript code to
the top of the web page.
Step 2. Copy the following code into the web page.
<!-- Configuration via data-key attributes -->
<form method="POST">
<script id="cko_script_tag" src="https://sandbox.company’s name.com/js/v1/comany.js"
data-public-key="pk_test_SPECIMEN-111"
data-payment-token="pay_tok_SPECIMEN-000"
data-customer-email="customer@email.com"
data-value="100"
data-currency="GBP">
</script>
</form>
Between the <form>and the </form> there are the <script> and </script> embedded into the form
which tells the browser that it’s a form the developer would like to display. The form allows the
browser to display the resources by the action of the POST attribute.
The <form method="POST"> is a HTML tag telling the browser to POST the following information
between the <form method="POST"> and </form>.
The JavaScript elements are presented within the form, in the <script id="cko_script_tag"
src="https://sandbox.company’s name.com/js/v1/comany.js"
This gives the script the name and displays it as cko_script_tag. This is also a link to the HTTP:// host
src=https://sandbox.company’s name.com/js/v1/comany.js
The next section of the script initialises the following:
data-public-key="pk_test_SPECIMEN-111"
This is where the API public key which was given to the merchant when the account was created is
inserted, within the quotes.
7. 6 | P a g e
data-payment-token="pay_tok_SPECIMEN-000"
This is the handling of the payment token.
data-customer-email="customer@email.com"
The customer’s email address, will be inserted here.
data-value="100"
This is the amount of the transaction, depending on the total transaction.
data-currency="GBP">
The currency at this point is pounds sterling but other currencies can be used.
</script>
The script is then closed and as well as the form </form> .
8. 7 | P a g e
The customer’s card charged and the confirmation to the merchant server
displayed.
Step 3.
The security of your customer’s card details and other sensitive data will not be transmitted through
the merchant’s server(s). We at (company’s name) will handle the most complex areas of the PCI
compliance for the merchant. This includes the encryption of the card details and redacting logs. By
using our company’s name.js you will never have to worry about managing sensitive cards data.
Company’s name.js form has an embedded script tag with a hidden entry called cko-payment-token.
This entry will be added to the form whenever a card is charged. The form will then be submitted to
the merchant’s server for the payment token to be verified.
9. 8 | P a g e
Verification of the payment token.
At this point the customer’s payment which includes the charge from the customer’s card will be
waiting for the merchant’s server to verify the payment.
The developer has two options in handling the charge requested either by Java or JavaScript. For the
Java developers: the request to the server is now waiting for the payment token charge which was
made from the customer’s card. This needs the server to verify it.
Step. 4
Copy the following code into your Java class file:
String paymentToken = "pay_tok_7a66140a-ffc9-48a7-80c3-6e1b70e8076d";
try {
// Create APIClient instance with your secret key
APIClient ckoAPIClient= new APIClient("sk_093F4C8D-E608-4B8D-9B39-
8C2491345864",Environment.LIVE);
// Submit your request and receive an apiResponse
Response<Charge> apiResponse = ckoAPIClient.chargeService.verifyCharge(paymentToken);
if(!apiResponse.hasError){
// Access the response object retrieved from the api
Charge charge = apiResponse.model;
} else {
// Api has returned an error object. You can access the details in the error property of the
apiResponse.
// apiResponse.error
}
} catch (Exception e) {}
From <http://developers.company’sname.com/docs/server/api-reference/charges/verify-charge>
The payment token is initialised and created within this line: String paymentToken =
"pay_tok_7a66140a-ffc9-48a7-80c3-6e1b70e8076d"; .
The try {, this opens up the try block and it monitors errors.
APIClient ckoAPIClient= new APIClient("sk_093F4C8D-E608-4B8D-9B39-
8C2491345864",Environment.LIVE);
The APIClient creates the ckoAPIClient to a new APIClient which passes the public key and the value
as a string.
10. 9 | P a g e
Response<Charge> apiResponse = ckoAPIClient.chargeService.verifyCharge(paymentToken);
The response method allows the charge variable to get the secret key ckoAPIClient as well as the
payment token that was requested from the customer.
if(!apiResponse.hasError){
An if else statement opens with the if statement checking whether or not the apiResonse has an error.
Charge charge = apiResponse.model;
This allows the charge attribute to be accessible and mapped to the apiResponse. The apiResponse
will then grant access to the ckoClient and paymentToken that was requested by the customer. This
allows access to the server and maps the apiResponse.
} else {
The else statement is now opened to handle errors from the apiResponse, once an error accords the
developer will be able to access and view the error type by accessing our apiResponse.error file.
}
} catch (Exception e) {}
The catch block is called to handle the Exception of type e when it is invoked. This block is executed
at the Java runtime and it will handle the Exception of type e from the apiClient public key.
Copy the following code into the same class file as above.
{
"id": "charge_B41BEAAC175U76BD3EE1",
"liveMode": true,
"created": "2015-04-07T16:31:58Z",
"value": 4298,
"currency": "usd",
"trackId": "TRK12345",
"description": "charge description",
"email": "LanaSMartin@dayrep.com",
"chargeMode": 1,
"transactionIndicator": 1,
"customerIp": "96.125.365.51",
"responseMessage": "Approved",
"responseAdvancedInfo": "Approved",
"responseCode": "10000",
"status": "Authorised",
11. 10 | P a g e
"authCode": "634622",
"isCascaded": false,
"autoCapture": "N",
"autoCapTime": 0,
At this point in the code the server returns the charge with the customer’s payment information
highlighting the customer’s card details, amount in US dollars(in this case), the description of the
charge, the email address, the customers IP address and, a message saying the payment has been
authorised or declined with the date and time displayed.
Copy the following code into the same class file as above.
"card": {
"id": "card_6AF19164-3233-4825-BEF9-143F04DA2E94",
"last4": "4242",
"paymentMethod": "Visa",
"fingerprint": "C96C9E67-DF9A-442A-93C5-CEEE7955314B",
"customerId": "cust_81AEE254-49C6-4AA0-A775-993669C5BDAD",
"name": "Sim Haag",
"expiryMonth": "06",
"expiryYear": "2018",
"billingDetails": {
"addressLine1": "72 Myrna Parkways",
"addressLine2": "Hoppe Fork",
"postcode": "aq81ct",
"country": "US",
"city": "Serenamouth",
"state": "Luzmouth",
"phone": {
"countryCode": "44",
"number": "12345678"
}
},
"cvvCheck": "Y",
"avsCheck": "S",
"responseCode": null
},
This point shows the last 4 digit of the customer’s card, the payment method (in this case is Visa). The
fingerprint and customer’s identity including the customer’s name is shown. The month and year or
the card expire date is also shown as well as the customer’s billing address, postcode, country, city,
state with the customer’s phone number and, CSV number checked and verified.
12. 11 | P a g e
Copy the following code in the same class file as above.
},
"metadata": {
"key1": "value1"
},
"shippingDetails": {
"addressLine1": "333 Cormier Bypass",
"addressLine2": "Rolfson Alley",
"postcode": "ue0 2ou",
"country": "US",
"city": "Schmittchester",
"state": "Jakubowskiton",
"phone": {
"countryCode": "44",
"number": "12345678"
},
This is the metadata displaying the results of the key and its value. It is also presented in the header
as well as the customer’s shipping address details including the postcode, country, city, delivery and,
contact number which are shown in a printable A4 paper.
Copy the following code in the same class file as above
"products": [
{
"description": "Tablet 1 gold limited",
"image": null,
"name": "Tablet 1 gold limited",
"price": 100,
"quantity": 1,
"shippingCost": 10,
"sku": "1aab2aa",
"trackingUrl": "https://www.tracker.com"
},
This displays the product description, name of the product, price, quantity, shipping cost and, SKU are
presented and tracked to https://www.tracker.com website, which provides the protection of customers’
sensitive data that are transported over the internet.
13. 12 | P a g e
Copy the following code in the same class file as above:
{
"description": "Tablet 2 gold limited",
"image": null,
"name": "Tablet 2 gold limited",
"price": 200,
"quantity": 2,
"shippingCost": 10,
"sku": "1aab2aa",
"trackingUrl": "https://www.tracker.com"
}
This is repeated depending on the quantity of the product and the price. Increases will happen each
time an additional item is added.
Now copy the final code in to the same class file as above.
},
"udf1": "udf 1 value",
"udf2": "udf 2 value",
"udf3": "udf 3 value",
"udf4": "udf 4 value",
"udf5": "udf 5 value"
}
You have now created a client-server application using the RESTful API with Java and JavaScript for
the use of our online payment transaction over, the HTTP protocol.
14. 13 | P a g e
Appendix:
Company’s name.js
Data-Key Attributes Javascript Keys Description
data-public-key publicKey Your public key obtained from company’s name Hub
data-payment-token paymentToken Your payment token
data-customer-email customerEmail Customer e-mail address
data-value value Transaction value
data-currency currency Transaction currency
15. 14 | P a g e
API KEYS
Key type Key subtype Prefix Description
Private
(secret)
Only used for requests from the merchant server to the API
Live ‘sk_’ Live mode
Test ‘sk_test_’ Test mode
Public Used for requests from the client (browser) to the API
Live ‘pk_’ Live mode
Test ‘pk_test_’ Test mode
