Checkout

Easiest way to integrate Pencepay is to use the Checkout feature. Checkout workflow involes redirecting customer's browser to Pencepay secure hosted pages where the actual payment takes place.

The advantages of using Checkout is that everything is already prepared for you; this means that you don't need to worry about how to present various payment methods, translation of text and amounts, credit card acceptance forms and in general security requirements for your website are trivial (you don't even need to have an SSL certificate). Checkout is a good option for very small merchants, or for merchants without special requirements, or for occasional acceptance of online payments. In those cases Checkout can be ideal.

Request

Integrating Checkout means preparing certain HTTP parameters on your side, and sending them via POST method to the gateway. This means that customer's browser will make the POST to Pencepay directly, and the result will be that customer is redirected to the secure payment page, and presented with payment instructions based on which payment methods are activated for your account.

Charset used with the data sent to the gateway should be UTF-8.

Creating a request

To initiate a payment through the Checkout, you need to instruct the customer's browser to make a POST request to the following endpoint:

https://secure.pencepay.com/service/1.0/checkout

publicKey: Public key of the User with permissions to use the Checkout feature. You can setup this easily in the Administration tool, under Setup - Users - Keys.
amount: Amount you wish to charge to the customer.
currencyCode: 3-letter ISO 4217 currency code (e.g. EUR). See a list
orderId: Internal reference you use to track this payment. For example ID of the invoice/proposal/order being paid, or any other ID. You can use this orderId later in the Administration tool and in data export to search through your transactions easily. Make sure that the orderID is human readable, short and does not contain whitespaces.
description: Short description of what the customer is paying for. Only 150 or less characters are allowed, without any HTML markup.
cancelUrl: URL on your server to which customer's browser will be redirected in case customer chooses to cancel the payment on the Checkout page.
redirectUrl: URL on your server to which customer's browser will be redirected after payment attempt by the customer (both successful and unsucessful). Make sure to check if the payment was successful.
customer.*: All Customer object properties, e.g customer.name, customer.email, customer.phone etc. All customer.* properties are optional.
billingAddress.*: All Address object properties, e.g address.addressLine1, address.city, address.postalCode etc. All billingAddress.* properties are optional.
tags: Tags associated with this transaction. Multiple tag codes are allowed.
customData: Map/Dictionary of the custom data fields and values which you provide, which is saved on the gateway with the transaction.
locale: Locale for payment page and the email notifications sent to the customer. For example hr-HR will show Croatian language page, and en-GB will show English version. 'en-GB' locale is default.
reserveFundsOnly: Used with credit card payments only. Causes the credit card payment to be AUTHORIZED only (funds are only reserve on the card, but not yet charged), so that you can later capture (actually charge) the funds using the appropriate API methods, or through the Administration tool.
signature: Request signature/digest created on select request fields. The purpose of this signature is to make sure that the POST request to gateway is coming from an authorized source (i.e. your website).

To create the request parameters use the library method generateCheckoutParameters. Make sure to configure the library first, as this method assumes that the public and secret keys are already set.

// TODO

At this point you should generate a HTML form (with the parameters prepared above) and instruct the customer's browser to POST the form data to Checkout endpoint. There are several ways you can do this, we suggest using Javascript code which performs the submit immediatelly, e.g. using BODY onLoad event.

Responses from the gateway

Once the payment process is complete (either successfuly or unsuccessfuly), you will receive two responses: redirect of customer's browser to your redirectUrl and optionally an Event sent by the gateway to your Callback URL(s).

It can happen that you never receive the redirect to redirectUrl and cancelUrl, for example because the browser crashed, or because customer (accidentaly) closed the browser after the payment was processed, but before customer's browser got redirected. Customer can even close the browser after reaching the Checkout, but before even attempting to pay. This is why it is advised to use Events as well.

Browser redirect to redirectUrl

Once the payment is complete, we will redirect the customer back to your redirectUrl. As anyone can call this URL (if he knows it), we will send you only the transactionUid parameter appended to your redirectUrl.

The make sure the request came from the gateway, and to get the full transaction details (including any custom data you might have sent in the request), you should now fetch the transaction from the gateway using the library.

// Get "transactionUid" parameter using your framework
String transactionUid = parametersMap.get("transactionUid");

Transaction transaction = gw.transaction().find(transactionUid);

// Do your stuff, e.g. check transaction status

if (transaction.getFailureCode() > 0) {
    // Declined
    transaction.getFailureMessage();
} else {
    // Success
    transaction.getId();
}

Of course, if you are also using Callbacks to receive Events, then you have probably already received the Event in the background, so you can just use the data you have already saved in your database (correlated by the transactioUid), without fetching the transaction again from the gateway.

Browser redirect to cancelUrl

When customer is redirected to cancelUrl this means that customer has intentionally cancelled the payment process. Do whatever housekeeping you need in your application.

Handling Events

Together with the browser redirect to redirectUrl, you can choose to receive Events as well, which are sent directly from the gateway to your Callback URL (as no browser redirect is used with Event, they are much more reliable).

Thus, you can be sure that you will have information about the payment even if the customer's browser crashed, or any other error occured.

You configure the Callback URL(s) in the Administration tool.

Other transaction actions

All the other actions on the transaction created using the Checkout can afterwards be captured, voided, refunded etc. using the Pencepay library.

Please follow the library instructions to find out about everything you can do after the transaction is created.