PencePay Integration Manual

PencePay
Hosted Payments
Integration Manual for connecting websites to PencePay using hosted payment page

Document by: PencePay Limited
Last update: 15.10.2013. v1.7.1

PencePay Limited
www.pencepay.com | supportpencepay.com
Content
Content .............................................................................................................................. 2
Introduction ....................................................................................................................... 4
Card payments ................................................................................................................... 4
Online credit and bank transfers ........................................................................................ 4
eWallets ............................................................................................................................. 4
Free Test account ............................................................................................................... 4
Basic setup ......................................................................................................................... 5
Service URLs ....................................................................................................................... 5
Test payment instruments ................................................................................................. 5
Request parameters ........................................................................................................... 6
Request digest ................................................................................................................. 11
Response parameters ...................................................................................................... 12
Hosted Payment Page use examples ......................................................................................... 12
Notifications .................................................................................................................... 14
Status codes and constants .............................................................................................. 16
Payment methods ..................................................................................................................... 16
Transaction types ...................................................................................................................... 16
Languages ................................................................................................................................. 16
Response codes ......................................................................................................................... 17
Notification types ...................................................................................................................... 18
Country codes ........................................................................................................................... 18
Currency codes .......................................................................................................................... 18
About us .......................................................................................................................... 19
Copyright

Copyright PencePay Limited 2013. All rights reserved.

Document changes
PencePay 2013
PencePay Limited

Version
1.7
1.6
1.5.2
1.5.1
1.5
1.4
1.3
1.2
1.1
Date
03.10.2013.
10.05.2013.
04.09.2012.
26.06.2012.
20.04.2012.
20.03.2012.
06.02.2012.
03.02.2012.
25.12.2011.
PencePay 2013
Changes
Mobile integration and notes moved to separate document.
New signature generation method. Fields explanations fixed.
Service URLs updated. Signature explanation added.
Notification statuses updated.
Mobile payment changes, examples added for all payment methods.
Online banking payments and banking transfers instructions added.
Response codes updated
Service URLs and Test account instructions.
Updated integration documentation to PencePay branding.
PencePay Limited
Introduction

PencePay is an online payments service that allows merchants (i.e. commercial websites,
bloggers, charities and others) to accept online payments from customers. Service enables a
merchant to easily integrate card payments, eWallets, online credit and bank transfers
through a simple API.

This document contains technical instructions for connecting to PencePay for large
payments.

Card payments

All the major international credit cards are supported through a Hosted Payment Page or a
direct integration scenario (check availability of direct integration scenario with PencePay
Sales availability depends on which acquiring bank is used).

Online credit and bank transfers

So called online credit or real-time banking payment are supported. Customer pays
directly from his bank account, without a need of a credit card, and you get a real-time
information about the purchase status. This way you can deliver the product/service
immediately and receive funds from the customer later.

eWallets

PencePay is fully integrated with Moneybookers eWallet and can thus enable merchant to
accept payments from customers who are already registered with Moneybookers or which
are just unregistered one-time buyers.

PencePay Sales helps you with all the administrative tasks required to open Moneybookers
merchant account.

Free Test account

The way to develop and test integration before going live, is to open Test account with
PencePay. You can easily open a free Test account at www.pencepay.com.

You will receive email with the connection and access details for your newly opened account
after filling the online free test account opening form.

PencePay 2013
PencePay Limited
We will never ask you for your password. If you loose your password that you entered in the
Test account registration process, there is an option for resetting the password on the login
page, or PencePay Support can reset it for you.

Basic setup

In order to use PencePay with any one of the available integration methods, you will need
some basic parameters which identify your website in our system:

(required) merchant code (API username) and
(optional) request signing key (API password).

Go to Setup -> Merchant Profile -> API access to access this information if you don't have it
already. You can use this data to access PencePay services as described in the next chapters.

Service URLs

PencePay services are available at the following URLs, depending on the service needed.

https://secure.pencepay.com/service/hosted/1.0/
(hosted payment page)

https://secure.pencepay.com/service/direct/1.0/
(direct HTTPS POST-based transparent integration)

Notice: slash at the end of a service URL is important.

Test payment instruments

To receive test credit cards and other testing payment credentials, please send email to
support@pencepay.com with the request. Please include the e-mail of your account in the
PencePay system in the request.

PencePay 2013
PencePay Limited
Request parameters

The table describes all the possible parameters for HTTPS integration with PencePay. This is
an overview of parameters, while in the next chapter of this manual you can find the
concrete integration scenario examples.

Field name
Required Format Allowed values
Description
/ Example

BASIC PARAMETERS

mch_code
AN
0016512
Identification
o
f
t
he

merchant performing this
request. Same as API
Username.
action_type
AN authorization,
Type of transaction you

sale, refund,
wish to perform in this
void,
request. See full list. For
subscription
automatic completion of
card authorizations, send
sale.
payment_methods

visa,
Filter
p
ayment
m
ethods

mastercard,
displayed on the Hosted
sms,
Payment Page.
bank-transfer,
online-credit

amount
N
10000 (for Smallest parts of currency,

100.00 EUR)
i.e. EUR amount in cents.
currency
AN (3)
GBP, EUR ISO 3-letter currency code

in uppercase.
order_id
AN
INV01512-11
Reference
for this

(250)
transaction in your system,
i.e. invoice number.
dept_code
AN (50)
default
Internal name of the

department. Used for
better sorting of
transactions in the Admin
and for better transaction
reports. Can be found in
Admin under Setup ->
Departments (internal
name).
PencePay 2013
PencePay Limited
charset
AN(20)
utf-8
lang
AN(2)
en, hr
signature
AN
(100)
Digest of
request values.
John
Hancock

New York
1000
GB

CUSTOMER INFO

customer_name
customer_surname
customer_address
customer_city
customer_zip
customer_country
AN
AN
AN
AN
AN
AN(2)
customer_email
AN
customer_telephone
customer_msisdn
AN
N (30)
Charset in which you are

sending us data, in case
different than utf-8. We
will convert data to utf-8
for you so that all
characters are processed
and displayed correctly.
Language of the hosted
payment page, in case we
have a control over this
page for the selected
payment method.
Request MD5/SHA1
signature, lowercase. See
details about forming a
request digest bellow.

ISO 4217 2-letter code of
the country, uppercase.
Email address
Email of the customer. In
case of eWallets it is used
for customer identification.
003851353577

38591631632
Mobile phone number in
international format.

PAYMENT CARD PROCESSING FIELDS

card_number
N (16)
card_cvd
AN(4)
card_expmon
N(2)
05
card_expyear
N(2)
15
PencePay 2013

Card number without
spaces or dashes.
Security code printed on
the card (i.e. 0548).
Expiry month from the
card.
Expiry year from the card
(i.e. 15 for 2015).
7
PencePay Limited
installments
N(2)
Number of monthly
installments for this card
payment. This is unrelated
to subscriptions and
availability depends on the
country and card brand.

ONLINE CREDIT

bank_sortcode
bank_country_code
AN(50)
AN(2)
2700002
GB
fieldA,fieldB

Sort code of the bank.
ISO 4217 2-letter code of
the country where the
account is located,
uppercase.

RESPONSE CONTROL FIELDS

return_fields
AN(255)
accept_url
URL
cancel_url
URL
status_url
URL
PencePay 2013

Return only the fields
specified, from all fields
that were sent in the
request. Comma separated
list of fields. If not
specified, all request fields
are echoed in the
response.
We will redirect customer
to this URL only if the
transaction was a success.
This URL will receive
additional parameters
from us, as described in
Response parameters
chapter.

Where to redirect a
customer after he cancels
payment on the hosted
payment page.
If this field is provided and
non-empty, we will send
notification to the given
URL. Read more in Status
update section.
8
PencePay Limited
redirect_url
URL
CUSTOM FIELDS
custom_field1
AN
(255)
custom_field2
AN
(255)
custom_field3
AN
(255)
PRODUCT / SERVICE INFO
If provided customer is, on

a completed purchase,
redirected to this page,
regardless of the payment
outcome. This is used
together with status_url
for reliable asynchronous
payment processing
notification of the
webshop.

Any value you wish to be
preserved in our
transaction record (i.e.
customer reference ID in
your system, customer
type etc.).

Any additional value you
wish to be preserved in our
transaction record.

Any additional value you
wish to be preserved in our
transaction record.

product_name
AN
product_description
AN
Name of the
product/service you are
selling. It it will be
displayed on the top of the
page in Order details.
Description of the
product/service you are
selling. It it will be
displayed on the top of the
page in Order details. If
used you also have to
provide product_name.

PencePay 2013
PencePay Limited
PencePay 2013
10
PencePay Limited
Request digest

Each request to PencePay must be digitally signed in order to be accepted. This is done by
digesting important request fields, together with a secret known to both parties, into a
request digest.

Digest is formed by concatenating multiple request fields (make sure they are not URL-
encoded before you concatenate them) and feeding the request to the MD5 or SHA1
hashing function.

Legacy digest data (for old integrations) is calculated using the fields as follows:

md5(mch_code+order_id+amount+currency+dept_code+payment_policy+secret_key)

Payment_policy field is a field used by some of legacy integrations with PencePay, it can be
left blank for new integrations.

PencePay 2013
11
PencePay Limited

Response parameters

Once the transaction is complete, we will return to your accept_url the appropriate
parameters, depending on the transaction type and response settings you sent us in the
transaction request.

Field name
Always
Description
present

response_code
Our result code for this request.

See full status codes table below.
response_message
Our response message related to the response code.

amount
Amount of the transaction

payment_method
Internal code for the payment method used.

tid

Transaction ID in our system.

order_id
Transaction
I
D
o
r
o
rder
reference in your system.

custom_field1,
We will send you back your custom fields if you sent

custom_field2,
them in the initial request.
customer_field3
signature
Digest of our response data, which you can check on

the receiving side.

Notice: if you set the return_fields field in the request, we will also return in our response
the specified fields from the initial request.

Signature in the response to accept_url is generated by PencePay by calculating MD5 hash of
the these fields:

md5(tid+order_id+payment_method+amount+secret_key)

Hosted Payment Page use examples

Hosted payment page is used to authorize payments for different payment methods, as per
parameters described in Request parameters section.

Example of using Hosted Payment Page for processing cards, online credit and/or bank
transfers:

PencePay 2013
12
PencePay Limited
<form method="POST"
action=" https://secure.pencepay.com/service/hosted/1.0/">
<input type="hidden" name="mch_code" value="merchant1" />
<input type="hidden" name="signature" value="xxxxxx" />
<input type="hidden" name="order_id" value="17134" />
<input type="hidden" name="dept_code" value="maindept" />
<input type="hidden" name="amount" value="1100" />
<input type="hidden" name="currency" value="EUR" />
<input type="hidden" name="accept_url" value="http://your.url" />
<input type="hidden" name="cancel_url" value="http://your.url2" />
<input type="hidden" name="status_url" value="http://your.url3" />
<input type="hidden" name="amount" value="30100" />

<input type="hidden" name="my_field" value="my_value" />
<input type="hidden" name="return_fields" value="my_field1" />
</form>
PencePay 2013
13
PencePay Limited
Notifications

During the online purchase customer can simply close the browser in the middle of the
purchase process, or a technical error can cause the process to be interrupted. This is why,
for applications where you need very reliable information about the purchases made, you
must use the Notifications (or Status update) functionality.

Notification means that PencePay server will call your server and inform you about
transaction status and other changes, through a direct server-to-server HTTPS connection.
This way, even if the customer closes the browser, your server will still receive notification
about the status of the transaction.

Notification URL is provided by you in each initial transaction request and it will be used for
all notifications sent related to that particular transaction.

Field name
Always
Format
Description
present
notification_type
AN
Code specifying the current status of the

transaction (i.e. refunded, voided etc.) from
the notification codes.
response_code
N
Our result code for this request. See full

status codes table below.
response_message
AN
Our
r
esponse
message related to the

response code.
signature
AN
MD5/SHA1 digest of our response data,

which you can check on the receiving side.
tid

N
Our transaction ID.

transaction_time
AN
Time when the transaction event occurred

in our system.
test
AN
Test
o
r
p
roduction
t
ransaction
(true / false).

payment_method
AN
Payment method from the list of payment

method codes.
order_id
AN
Your transaction ID / order reference.

amount
N
Amount of the transaction.

currency_code
AN
Currency code of the transaction.

custom_field1,
AN We will send you back your custom fields if

custom_field2,
you send them in the initial request.
customer_field3

Notice: if you set the return_fields field in the request, we will also return in our response
the specified fields from the initial request.

PencePay 2013
14
PencePay Limited
Notification signature

You can check the notification signature to make sure it came from PencePay. Otherwise,
anyone could simulate the request and update your order status.

md5(tid+order_id+payment_method+amount+secret_key)

The other method you can use to protect your service is to limit access to it only to PencePay
IP address range, which is 89.19.240.*

PencePay 2013
15
PencePay Limited
Status codes and constants

Payment methods

Payment method
Visa
MasterCard
American Express
Maestro
Diners Club
JCB
Premium SMS (PSMS)
Premium Phone
Online Credit
Bank Transfer

Code
visa
mastercard
american-express
maestro
diners-club
jcb
premium-sms
premium-phone
online-credit
bank-transfer
Transaction types

Depending on the integration method used the following transaction types are available to
developers.

Code
Transaction type
authorization
Authorization
sale
Sale
void
Void
confirm
Confirm/Capture
refund
Refund

Languages

The following languages are currently supported on the Hosted Payment Pages.

Code
Language
en
English
hr
Croatian

Language can be changed by the customer during the purchase process, using the clearly
visible language selection menu on the hosted payment pages.
PencePay 2013
16
PencePay Limited
Response codes

These are the return codes returned by PencePay in Response and Status Update.

Code
Success
Description

0
Transaction successfully executed, regardless on the

transaction type (authorized, voided, captured, refunded)
100
Internal system error

200
Internal
e
rror
i
n
r
emote
processor's system

210
Internal error in remote acquirer's processor

300
Transaction declined by the issuing financial institution

1001
Service not set for the pipeline

1002
Merchant service not set

1003
No
d
evice
i
s
r
egistered
for the selected acquirer

1004
Transaction reference invalid

1005
Invalid response received from backend

1006
This Order ID was already processed

1007
Installments above maximum allowed for merchant

1010
No acquirer assigned to merchant for this service

1011
No route for the merchant acquirer

1012
No active route available to acquirer

1013
Unknown and/or unsupported card brand

1014
Test cards are disabled for this merchant

1015
3-D
Secure customer authentication failed

1016
Invalid customer HTTP session

1017
Invalid persisted customer session

1019
Amount cannot be higher than in the first authorization

1020
Authorization is not settled yet

1022
Action attempted on a transaction with invalid state

1023
Invalid currency provided for this action

1024
Payment Link is invalid

1025
Payment Link has expired

1026
Error
i
n FX currency conversion

1027
Device authentication failed

1028
Unknown device

1029
Error in Fraud Filter

1030
System encryption error

1031
Device is blocked

1032
Salespoint unknown

1033
Salespoint is blocked

1034
Merchant unknown

1035
Merchant
is blocked

1036
Unknown department code

9000
Invalid parameters provided in the request

PencePay 2013
17
PencePay Limited
9001
9002
9003

Invalid digest/signature provided in the request

Invalid card number
Invalid expiry date
Notification types

Notifications are sent for successful transaction events.

Code
authorized
sale
voided
confirmed
refunded

Notification type
Authorization
Sale
Void
Confirm
Refund
Country codes

Country codes are defined in ISO 42171. Example: GB, HR, US.

Currency codes

Currency codes are defined in ISO 3166-12. Example: USD, EUR, HRK, SGD.

1
2
http://en.wikipedia.org/wiki/ISO_3166-1
http://en.wikipedia.org/wiki/ISO_4217
PencePay 2013
18
PencePay Limited
About us

PencePay.com is an online payments service with 6+ years of experience.

PencePay Limited
www.pencepay.com

Technical integration support is available to merchants and their developers at
support@pencepay.com or at +385 1 3535 078.

Learn more about the service and the company at http://www.pencepay.com

PencePay 2013
19

PencePay Integration Manual

Hochgeladen von

Dokumentinformationen

Copyright

Verfügbare Formate

Dieses Dokument teilen

Dokument teilen oder einbetten

Freigabeoptionen

Stufen Sie dieses Dokument als nützlich ein?

Sind diese Inhalte unangemessen?

Copyright:

Verfügbare Formate

PencePay Integration Manual

Hochgeladen von

Copyright:

Verfügbare Formate

PencePay

Online credit and bank transfers

Test payment instruments

Charset in which you are

PRODUCT / SERVICE INFO

If provided customer is, on

Status codes and constants

Invalid digest/signature provided in the request

Das könnte Ihnen auch gefallen