Getting Started

Paymennt Integration Support

API Integration

INTRODUCTION

This document provides the integration details between the merchant & the PointCheckout systems. The integration allows the merchant system with its own shopping and order processing system to work in conjunction with PointCheckout system for the payments. The merchant would need the API credentials & the private secret key to access the PointCheckout API.

The process is outlined below:

  1. When a customer is ready to pay for their order/shopping cart on the merchant system, a “Pay using PointCheckout / Card” option is presented.

  2. On submitting the “Pay using Pointcheckout / Card” button, the merchant system processes the order & makes the “NEW CHECKOUT REQUEST” API call to PointCheckout & obtains a checkout key.

  3. On successfully obtaining the token from PointCheckout in the previous step, the merchant system then redirects the customer to PointCheckout passing in this checkout key (See PAYMENT PAGE REDIRECT).

  4. The customer then may either successfully complete the payment or cancel the payment.

  5. In any of the cases in the previous step, the customer is finally returned to the merchant system.

  6. Once the customer has been returned to the merchant system from PointCheckout, the merchant system makes the “GET CHECKOUT REQUEST” API call to retrieve the status of the payment and at this stage the checkout is now complete.



REQUIREMENTS

Below are the requirements that must be implemented in the shopping cart extension for PointCheckout.

  1. Add a new Payment Method to the checkout page called Card payment or Pay using PointCheckout.

  2. When the payment method to be used is POINTCHECKOUT, PointCheckout Logo from https://www.pointcheckout.com/en/image/logo.png must be presented to the customer at the payment page

  3. Should support the following configuration options:

    1. Support for Test / Live environments.

    2. Ability to restrict payment to users from specific countries

    3. Ability to restrict payment to users from specific user groups

    4. Ability to configure new order status


SETTINGS SCREEN

The settings screen for the PointCheckout payment method should include at minimum the following configuration options.




SUPPORTED ENVIRONMENTS

The PointCheckout Payment Extension / Plugin should support the following two environments; Test and Production. Throughout the API, they will be referred to as $BASE_URL and the admin can select the current environment in the administrator settings screen.

TEST ENVIRONMENT

Base URL

https://api.test.pointcheckout.com


PRODUCTION ENVIRONMENT

Base URL

https://api.pointcheckout.com



API REQUESTS

There are two relevant API requests within the checkout process:

NEW CHECKOUT REQUEST

This requests sends the checkout details to the PointCheckout checkout service. It returns a unique checkout id that would be used for the processing of the payment.

REQUEST URL

Request URL

$BASE_URL/mer/v1.2/checkouts

METHOD TYPE

Request Type

POST

HEADER PARAMETERS

HEADER

DETAILS

X-PointCheckout-Api-Key

The merchant API key.

X-PointCheckout-Api-Secret

The Merchant API Secret.

Content-Type

application/json

REQUEST BODY

The request is a JSON based object. It includes the following parameters

PARAMETER

TYPE

DETAILS

transactionId

String

A merchant unique transaction ID for this checkout. This can be the order ID. Must match any reference shown to the user during checkout / order history. (Required)

resultUrl

String

URL to redirect user to after a successful or failed payment. ( See Get Checkout Request)

amount(1)

Decimal

The amount customers must pay. (Required)

subtotal(2)

Decimal

Sum of all individual line items (without discount / tax / shipping / etc). (Optional)

shipping

Decimal

Total value of shipping. (Optional) 

handling

Decimal

Handling fees for the order. (Optional)

tax

Decimal

Tax value on order. (Optional)

discount

Decimal

Value of discount applied to Subtotal. (Optional)

currency

String

ISO 4217 Currency Code (3 letter currency code). (Optional)

deviceReference

String

Merchant device reference, to be used by the merchant to indicate the source device of the checkout if more than one device is used to submit checkouts to PointCheckout. (Optional)

paymentMethods(3) 

Array

Array containing payment methods to be available at the payment page. When left empty all available options will show. When provided the payment methods order in the payment page will follow the same order passed in this parameter. (Optional)

defaultPaymentMethod

Enum

Active payment method when opening the payment page. When left empty the default for your account at PointCheckout will be used. (Optional)

generateQR

Boolean

indicator to generate a Base64 QR image and include it in the response, default is false. (Optional)

qrSize

Integer

the size of the QR image in pixels, default is 300. (Optional)

sendCustomerEmail

Boolean

Indicator to send an email to the customer containing the payment link, this will only work if a valid email address  is passed in the customer request

sendCustomerSms

Boolean

Indicator to send an sms to the customer containing the payment link, this will only work if a valid phone number is passed in the customer request

expiryInMinutes

Integer

Number of minutes the payment will remain available, after that the payment will expire.. (Optional)

languageCode

String

2 Letter ISO 639-1 language code, for viewing the payment page. When the language is not supported, the system will revert to the default. (Optional)

var jsMessages = {}; jsMessages.complete = "Complete"; jsMessages.select = "Select"; jsMessages.pleaseSelect = "Please select"; jsMessages.recaptchaTerms = "<span>This site is protected by reCAPTCHA and the Google</span><span><a href='https://policies.google.com/privacy'> Privacy Policy</a> and </span><span><a href='https://policies.google.com/terms'>Terms of Service</a> apply.</span>"; jsMessages.show = "Show"; jsMessages.hide = "Hide"; jsMessages.loadMore = "load more"; jsMessages.help = "help"; jsMessages.uploadingAttachments = "uploading attachments"; jsMessages.processingAttachments = "processing attachments"; jsMessages.requestSubmitted = "Thank you! Your support request has been submitted. We will get in-touch with you shortly"; jsMessages.submitFailedWithError = "Failed to submit help request due to the following error"; jsMessages.submitFailedTryAgain = "Failed to submit help request, please try reloading the page and submit again"; jsMessages.faildToUploadAttachment = "Failed to upload attachment"; jsMessages.attachmentFileSize = "File size may not exceed 15 MB"; jsMessages.fileAlreadyAttached = "This file is already attached"; jsMessages.helpWithCheckout = "Help with this payment"; jsMessages.attachmentNotAllowed = "Attachment file type is not allowed"; jsMessages.nameCantContainAnySpecialCharacters = "Name can't contain any special characters"; jsMessages.thisFieldIsRequired = "This field is required"; jsMessages.mustBeANumber = "Must be a number"; jsMessages.cannotBeLessThan = "cannot be less than"; jsMessages.cannotBeGreaterThan = "cannot be greater than"; jsMessages.mustBeExactly = "Must be exactly"; jsMessages.charactersLong = "characters long"; jsMessages.cannotBeShorterThan = "cannot be shorter than"; jsMessages.characters = "characters"; jsMessages.cannotBeLongerThan = "Cannot be longer than"; jsMessages.doesNotMatchFieldRequirements = "does not match field requirements"; jsMessages.enterAValidEmailAddress = "Enter a valid email address"; jsMessages.enterAValidNumber = "Enter a valid number"; jsMessages.invalidCardNumber = "invalid card number"; jsMessages.enterAValidCardNumber = "Enter a valid card number"; jsMessages.unableToVerifyCardNumberMissingLibrary = "unable to verify card number. Missing jquery.payment.js library."; jsMessages.cardsAreNotSupported = "cards are not supported for this payment"; jsMessages.unableToVerifyCardTypeMissingLibrary = "unable to verify card type. Missing jquery.payment.js library."; jsMessages.invalidMustBe4digits = "invalid , must be 4 digits"; jsMessages.invalidMustBe3digits = "invalid , must be 3 digits"; jsMessages.mustBe4digits = "Must be 4 digits"; jsMessages.mustBe3digits = "Must be 3 digits"; jsMessages.unableToVerifyCVVMissingLibrary = "unable to verify CVV. Missing jquery.payment.js library."; jsMessages.atLeastOneItemShouldBeSelected = "at least one item should be selected"; jsMessages.mustContainAtLeastOneUpperCase = "Must contain at least one upper case character"; jsMessages.mustContainAtLeastOneLowerCase = "Must contain at least one lower case character"; jsMessages.mustContainAtLeastOneDigitCharacter = "Must contain at least one digit character"; jsMessages.unableToLoadContentTryReloading = "Unable to load content, try reloading the page"; jsMessages.unableToValidateCardNumber = "Unable to validate card number"; jsMessages.enterAValidPhoneNumber = "Enter a valid phone number"; jsMessages.invalidCountryCallingCode = "Invalid country calling code"; jsMessages.phoneNumberIsTooShort = "Phone number is too short"; jsMessages.phoneNumberIsTooLong = "Phone number is too long"; jsMessages.notAValidNameCanOnlyContainLetters = "Not a valid name, can only contain letters"; jsMessages.enterAValidExpiryDate = "Enter a valid expiry date"; jsMessages.CVCMustContainNumbersOnly = "CVC must contain numbers only"; jsMessages.unableToValidateCVC = "Unable to validate CVC";