Accepting e-commerce payments for merchants

Accepting e-commerce payments for merchants

iPayment Gateway API (IPG API)

Protocol Version 3.4

Document version 22

iCard AD © 2007 – 2020

2

Table of Contents

Version control ........................................................................................................................... 6

Security and availability.............................................................................................................. 7

Introduction ................................................................................................................................ 7

Test IPG API ................................................................................................................................ 8

Accepting e-commerce payments with IPG interface................................................................ 8

Overview ................................................................................................................................. 8

HTTP POST .............................................................................................................................. 8

Data Type Formats .................................................................................................................. 9

Signatures ............................................................................................................................... 9

Example ............................................................................................................................. 10

Signature verification example ......................................................................................... 10

Understanding transmission mechanism ............................................................................. 11

Method standard properties ............................................................................................ 12

Response standard properties .......................................................................................... 13

IPG methods (alphabetical order) ............................................................................................ 14

Purchase with payment card (API call: IPGPurchase) .......................................................... 15

Purpose ............................................................................................................................. 15

Method properties ............................................................................................................ 15

Cart Logical Record ........................................................................................................... 18

Example ............................................................................................................................. 18

Processing MOTO transaction by Merchant (API call: IPGMoto) ......................................... 19

Purpose ............................................................................................................................. 19


Example ............................................................................................................................. 20

3

First recurring transaction with payment card (API call: IPGFirstRecurring) ....................... 21

Purpose ............................................................................................................................. 21


Example ............................................................................................................................. 24

Processing subsequent recurring transaction by Merchant (API call:

IPGSubsequentRecurring) ..................................................................................................... 24

Purpose ............................................................................................................................. 24


Example of POST request .................................................................................................. 25

Example of the xml ........................................................................................................... 26

Successful payment notification (API call: IPGPurchaseNotify / IPGPurchaseOK) ............... 26

Purpose ............................................................................................................................. 26


Cancelation of payment notification (API call: IPGPurchaseCancel) .................................... 27

Purpose ............................................................................................................................. 27


Rollback of previous notification (API call: IPGPurchaseRollback) ....................................... 27

Purpose ............................................................................................................................. 27


Get transaction status for previously executed payment (API call: IPGGetTxnStatus) ....... 28

Purpose ............................................................................................................................. 28



Make a refund for previously executed payment (API call: IPGRefund) .............................. 29

Purpose ............................................................................................................................. 29


4


Make a reversal for previously executed payment (API call: IPGReversal) .......................... 30

Purpose ............................................................................................................................. 30



Store card (API call: IPGStoreCard) ....................................................................................... 31

Purpose ............................................................................................................................. 31


Example ............................................................................................................................. 33

Store Card Success Notification (API call: IPGStoreCardOK) ................................................ 34

Purpose ............................................................................................................................. 34


Store Card Cancelation Notification (API call: IPGStoreCardCancel) ................................... 35

Purpose ............................................................................................................................. 35


Purchase with stored card (API call: IPGPurchaseWithStoredCard) .................................... 35

Purpose ............................................................................................................................. 35




Processing Original Credit Transaction (OCT) (API call: IPGOCT) ......................................... 37

Purpose ............................................................................................................................. 37




IPG Payment Widget ................................................................................................................ 39

5

IPG Widget process ............................................................................................................... 39

Payment Token Request (API Call: IPGPaymentToken) ....................................................... 39

Purpose ............................................................................................................................. 39



Example of xml .................................................................................................................. 41

Create payment form ........................................................................................................... 41

Wrapper ............................................................................................................................ 41

JavaScript code .................................................................................................................. 41

Widget customization ........................................................................................................... 42

Appendix I – Error messages .................................................................................................... 43

6

Version control

Document version

Protocol version

Author Description Date posted

1 1.0 Yavor Petrov Version 1.0 (obsolete) 12.2009

2 2.0 Yavor Petrov Version 2.0 (obsolete) 05.2010

3 3.0 Yavor Petrov Version 3.0 first full 11.05.2012

4 3.0 Yavor Petrov Shopping card format changed 15.05.2012

5 3.0 Milena Dyankova Added “E-mail” field 22.05.2012

6 3.0 Milena Dyankova Added “MIDName” and “OrderLink” fields. Added Appendix I.

23.05.2012

7 3.1 Milena Dyankova Version 3.1

“RequestDateTime” and “RequestDateSTAN” parameters are removed from Method standard properties and are added to IPG Methods IPGPurchaseNotify / IPGPurchaseOK.

05.07.2012

8 3.1 Milena Dyankova Added signature example 15.10.2012

9 3.1 Milena Dyankova Added new IPG method (IPGCreditRequest) 15.09.2013

10 3.2 Ivayla Santeva Version 3.2

“Pan” parameter is added to IPG Methods IPGPurchaseNotify / IPG PurchaseOK

21.08.2014

11 3.2 Ivayla Santeva Added link with currently used signatures 14.10.2014

12 3.2 Ivayla Santeva Added method IPG Moto 21.03.2015

13 3.2 Ivayla Santeva Added methods IPGFirstRecurring and IPGSubsequentRecurring

01.07.2015

14 3.2 Suzan Dermendzhieva

Updated xml example of IPGGetTxnStatus 23.11.2015

15 3.2 Rayna Lazarova Added new Status values (6 to 9). 21.06.2018

16 3.2 Rayna Lazarova Added method IPGStoreCard, IPGStoreCardOK, IPGPurchaseWithStoredCard, IPGStoreCardCancel.

11.10.2018

17 3.2 Rayna Lazarova Added method IPGOCT. 14.08.2019

18 3.2 Ivayla Santeva Added IPG widget description 02.10.2019

19 3.3 Ivayla Santeva Processing of CUP transactions 05.10.2019

20 3.4 Suzan Dermendzhieva

Added new parameters related to EMV 3DS protocol

01.03.2020

21 3.4 Ivayla Santeva IPGGetTxnStatus changed output 11.06.2020

22 3.4 Ivayla Santeva Added statuses in response of IPGGetTxnStatus

03.11.2020

7

Security and availability Connection between Merchant and iCARD is handled through internet using HTTPS protocol (SSL over

HTTP). Requests and responses are digitally signed both. iCARD host is located at tier IV datacenter in

Luxembourg. Public address for IPG is BGP enabled and available through all first level internet

providers.

Exchange folder for partners (if needed) is located at a SFTP server which enables encrypted file sharing

between parties. The partner receives the account and password for the SFTP directory via fax, email

or SMS.

iCARD supplies an emergency support line via e-mail or phone which is 7x24 enabled and reaches

certified engineers.

Introduction This document describes the interface for e-commerce payments via payment gateway. The Merchant

should integrate the iPayment Gateway API (IPG API) at the site accepting card payments. IPG API will

gain access to the entry point of iPayment Gateway (IPG) managed by iCard AD (iCARD). IPG will handle

and guide the cardholder during the payment process, will check the card sensitive data and will

process a payment transaction through card schemes (VISA, MasterCard, JCB).

IPG API will provide:

• Secured page and Secured communication channel with the Merchant

• Storing of merchant private data (shopping cart, amount, payment methods, transaction

details etc.)

• Financial transactions to VISA, MasterCard, JCB – transparent for the Merchant

• Operations for the front-end: Purchase transaction

• Operations for the back-end: Refund, Reversal, Get Transaction Status

• 3D processing

Out of scope for this document:

• Merchant statements and payouts

• Merchant back-end (iMerchant)

The purpose of this document is to specify the IPG API Interface and demonstrate how it is used in

the most common way.

All techniques used within the interface are standard throughout the industry and should be very

easy to implement on any platform.

Continue on next page

8

Test IPG API A “by appointment” test service is available which allows the validation of the API calls. Testers should

negotiate an exclusive access to the testing service and ensure monitoring by iCARD engineer.

Accepting e-commerce payments with IPG interface

Overview

7

Web Server

Merchant

Authorization system

iCard AD

Card Schemes

VISA, MasterCard, JCBWeb Shop

Checkout page

Internet Customer

1

2

5

3

8 6

4

IPayment Gateway

1. Internet customer at web shop checkout page

2. Payment initiated by customer.

3. Merchant web server initiates payment through IPG. Merchant web server should

redirect the browser to IPG web address.

4. Customer web browser is redirected to IPG web page.

5. Customer is requested to input the card data and press PAY. IPG handles the 3D secure

processing and financial transaction messaging.

6. IPG receives the details for the payment – successful or declined.

7. IPG passes the result to Merchant Web Server.

8. IPG redirects to Web Shop “checkout result” page.

HTTP POST

Data transfer between Merchant and IPG is made by HTTP POST. All the parameters for the requests

are in the body in [parameter=value] form. Separator between tokens is [&]. The body is URL Encoded.

Character encoding is UTF-8.

Example: POST /somescript.php HTTP/1.1 Host: www.somesite.com User-Agent: Mozilla/4.0 Content-Length: 27 Content-Type: application/x-www-form-urlencoded userid=joe&password=guessme&user_type=1

9

Data Type Formats

Data Type in document

Description Example

int integer 1

String string This is a string

Date ISO 8601 date string YYYY-MM-DD 2012-03-31

DateTime ISO 8601 datetime string YYYY-MM-DD HH:mm:SS

2012-03-31 23:59:59

A(n) Alpha string. [n] characters required Alpha string

AN(n) Alphanumeric string. [n] characters required

Alphanumeric string

N(n) Numeric string. [n] characters required. Number is left-padded with zeroes.

000123

double Numeric string with decimal point. Only point is used (no commas or other characters for decimal point)

34.56

BASE64 Sting used to pass binary data. The binary data should be converted to base64 standard.

YW55IGNhcm5hbCBwbGVhc3VyZQ==

XML Simple in place XML array. <body> <param>1</param> <value>2</value> </body>

Signatures

In every message a signature is supplied. The signature is a signed HASH of all the values from

properties sent in the request. All values must be URL encoded first.

For signing process, both iCARD and the Merchant generate public and private key pairs and exchange

the public keys. Key pairs are generated using RSA algorithm. Every of the parties are using the private

key to sign the message and the opposite side authenticate the sender with corresponding public key.

Signatures are calculated using the following mechanism. All data in POST request without the

Signature property is used to calculate hash using SHA1 algorithm. Then SHA1 value is signed with RSA.

The Signature property is concatenated at the end of the POST string. The opposite side should check

the signature in the same way. Calculate SHA1 for the POST string excluding the Signature section then

check with VerifySignature.

During the business lifecycle, there could be a need the keys to be changed, or more than one key to

be used in communication. IPG supports unlimited number of exchanged keys, for iCARD and Merchant

both. A key index is assigned to every key, starting from 1 to MAXINT. The key index of the key used to

sign the request is supplied as a parameter in every transmission.

Current test keys are available on: https://dev-ipg.icards.eu/sandbox/test_keys

https://dev-ipg.icards.eu/sandbox/test_keys

10

Example

<?php $postData = array('IPGmethod'=>'IPGPurchase', ............); #The $_POST array $privKey = '-----BEGIN RSA PRIVATE KEY----- MIICXAIBAAKBgQC8oMfOTxHN0WRPmRojUVeaj992GpzcoKibAc2i6P2yM0mOeYho TsdSpKzVYDRYrtGlRb8B2+4/R67nxM9O/Tn5YtGXkLEVXI4mWrGTTRZr8afF97zx t1bThu/fMxpDfKGSQoq/d5sd7wHiu/vAGo4XSVwXk5iQeZy+rP9pCO7rQQIDAQAB AoGASWTV2bRyXP8IZOBRh0RzLbSlYjLgrgflEssU1DqL2/aQvFsVdGCStdlVVoDk XU1ITWJh+7szbHPb3lp5v2ZQU8lVacwBpLY7RHZ/BXiwmcg3iMwqEFCF2S+cPijA EOXrvv0N7G8r1qYGfbEVs3mDtFaTCbJiAQFiUxfWGpmNK0ECQQDtgqf/azooeBWa 43UZnM+YIHVSkdQtsRVaw4gCv+RWZVonqjRg+zanqLzwSTcveRVSIZiu3CfG5/sk co54Ki51AkEAy0/yzlEiFOJv0q8eANEB5fGj5LVAC+9LBzbsmkO054s9HdbuThQZ YDGi2TI6YRx/l/uRMNYTSmKjYt79gWQIHQJAdVf3HndgrXve2L6GLVhPLE7lCB1q YgS6kzRFr24VJyY965jo9f1HnH/+kQzrSfYdtY1JvSKiOGCGsRQ0FWRpvQJBAI4u sxcmFjeUw68LWGgpwrIUcxGWz9uI1WeOOZkIkJL9BRjBHpbr53MmQ0Sxo7IWRAT9 oWQN0h/LK4gReifq1OECQGaKHRJ9JMLnIrF0a8wHKjM8PbEPu2oelfHK/HeHpJMK xnecld/4RwEx7ytm2+UvaDo1cjYu0ig0D127pT07+yk= -----END RSA PRIVATE KEY-----'; #This is an example of RSA private key $concData = urlencode(stripslashes(implode('', $_POST))); # You need to concatenate all values from $postData and to URL-encode the result $dataHash = sha1($concData); # Create sha1 hash of concatenated data $privKey = openssl_get_privatekey($privKey); openssl_sign($dataHash, $signature, $privKey); # Signed data in binary $signature = base64_encode($signature); # Base64 encoding of the signature $postData['Signature'] = $signature; # Now you need to add the signature to the post request

Signature verification example

$data = $_POST; $pubKey = '-----BEGIN PUBLIC KEY----- MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQC4ur+fZBqNjnm1XJSJrzf8vyIv xfXew44RKJv9kpPiSEtGaRiAmqZhMWsW/fD2Drnh1A6gCgfWIv/3Zgr18GZ/Heqm h5n9HmQndHAB2nZnFLOioL9v6awAbqVeqYBMzp97UkruxXDtqejL7w8WkxearqpU BBbcPHA2gMp0hRN/MwIDAQAB -----END PUBLIC KEY-----'; $signedData = $data['Signature']; unset($data['Signature']); $concData = urlencode(stripslashes(implode('', $data))); $pubKeyId = openssl_get_publickey($pubKey); $signedData = base64_decode($signedData); $res = openssl_verify(sha1($concData), $signedData, $pubKey); openssl_free_key($pubKeyId); if($res==1){ //success }else{ //not success

11

}

Understanding transmission mechanism

NO

Transaction Processing

IPG iCARD Authorization SystemMerchant

Https://ipay.bg/paymentpage

POST parameters:

Amount, MID,

URL_OK, URL_Cancel,

URL_Notify, etc.

Secured Payment page.

Cardholder

action

Merchant “Cancel Payment”

page

Cancel

Payment


processes payment

Press PAY

Is The Card 3D

secure enebled

NOIs 3D

authentication

Successfull

YES

Transaction Result from


NO

YES

IPG Notifies merchant on

URL_Notify for the result

Merchant checks the status

of the payment

Approved/Declined

Redirect to URL_Cancel

END

Is the payment

approved

Mark the order:

Paid / Not paid

IPG Waits for HTTP OK from

URL_Notify

Have HTTP OK

Redirect customer browser to

URL_OK

(END)YES

Process Reversal

(void)NO

Is the

Transaction

Approved

YES

12

Continues from previous page

Transaction Processing

iCARD Authorization SystemIPGMerchant

YES

NO

IPG Notifies merchant on

URL_Notify for transaction

VOID

Have HTTP OK

IPG Waits for HTTP OK from

URL_Notify

Process Reversal

(void)

Merchant marks the payment

as CANCELED (declined)

End Transaction

Schedule for next send.

Next send in 5 minutes.

In every request there are several parameters that are always supplied. Bellow they are called

‘standard properties’. Once defined bellow they won’t be described in every single command listed

below in the specification, they should be considered as existing to every command.

Method standard properties

Property Typical value Type Description

IPGmethod IPGPurchase String Name of the method requested for execution from IPG.

Signature Byte[] BASE64 Signed HASH for all properties in the command. Signature is ALWAYS THE LAST PARAMETER IN THE POST, as it is not used to calculate the hash.

KeyIndex 1 Int Identifier of the private key used for signature (if more then 1)

IPGVersion 3.3 string Version of protocol used for transition.

Language EN A(2) ISO 2-character code for the desired language on the payment page. If IPG cannot fulfill the requested language, it will set the English language as defaults.

13

Currently supporting EN, FR, DE, BG, ES, RO.

Originator 100 Int Value that uniquely identifies the merchant company that has signed a contract with iCard AD.

Response standard properties

Upon HTTP request, the party should respond with HTTP OK. Every other response should be treated

as communication error, call error, server error or system malfunctions.

In every HTTP response the party should include only the string OK. Every other content will be

considered as an error status.

14

IPG methods (alphabetical order) API function call Description

MERCHANT TO IPG

IPGFirstRecurring This is a method for processing a first transaction of subscription agreement.

IPGGetTxnStatus Returns the status and the parameters of a previously executed payment. Usually for back-office.

IPGMoto This is a method for processing a MOTO transactions by merchant.

IPGOCT This method is used by Merchant to initiate a transaction for sending money to a recipient or Gaming Repay. This transaction is related to previously executed Purchase transaction.

IPG PaymentTokenRequest

This method is a back-end synchronous request. Merchant’ system

sends all required information about payment transaction. In

response is received token, which must be used in next step.

IPGPurchase This is the standard method for checkout at web shop. IPGPurchaseWithStoredCard Performs a Purchase with previously stored card.

IPGReversal This command cancels a previously executed payment (void). Usually for back-office.

IPGRefund Credit to cardholder, e.g. return money. Usually for back-office.

IPGStoreCard Stores a card fir subsequent use. Returns a Token of the card.

IPGSubsequentRecurring This is a method for processing a subsequent recurring transaction after subscription by merchant.

IPG TO MERCHANT

IPGPurchaseNotify IPG will respond with this method on successful payment. The call will be made on previously supplied URL_Notify.

IPGPurchaseOK IPG will redirect with this method on successful payment. The call will be made on previously supplied URL_OK.

IPGPurchaseCancel

IPG will redirect with this method when the customer chooses cancel payment. The call will be made on previously supplied URL_Cancel.

IPGPurchaseRollback

IPG will notify that a reversal is passed for previous successful authorization. The merchant should mark the order as not paid (in case, the merchant has received IPGPurchaseNotify method). This is used when IPG do not receive and HTTP OK from the merchant as a response for IPGPurchaseNotify method.

IPGStoreCardOK IPG will redirect with this method on successful card storage. The call will be made on previously supplied URL_OK.

IPGStoreCardCancel

IPG will redirect with this method when the customer chooses cancel on store card. The call will be made on previously supplied URL_Cancel.

15

All commands described bellow do not include the standard properties discussed in the previous topic.

However the standard properties are mandatory for all commands.

Purchase with payment card (API call: IPGPurchase)

Purpose

This method initiates the beginning of the payment process for a cardholder. The cardholder is

placed on a page that requests entering payment card details.

IPG will check:

• Valid MID.

• Valid currency with regards to the MID.

Method properties

Property Typical value Type Required Description

MID 000000000000123 AN(15) YES Identifier of the virtual terminal used for the purchase.

MIDName Merchant Web Shop String YES User friendly name of the merchant web shop. The cardholder will see this name on some notices in the payment page.

Amount 23.45 Double YES The amount of the payment requested.

Currency 978 N(3) YES ISO numeric currency code. The currency for the payment must be equal to the currency of the MID.

CustomerIP 82.119.81.30 String YES Dotted-decimal string, that holds the customer IP address as reported at merchant web shop.

16

OrderID 201203319999999 String YES Placeholder for the merchant. Used to put some data that will help the merchant to recognize for which order is the payment. Up to 255 characters.

OrderLink http://site.ext/ String NO The link of the page with the order from the merchant web shop.

BannerIndex 1 Int YES Index specified in IPG for every banner provided by the Merchant. The Merchant may choose to select a proper banner for every payment. The banner is displayed on the payment page.

URL_OK http://site.ext/paymentOK String YES The page where the cardholder should be redirected on successful payment.

URL_Cancel http://site.ext/paymentNOK String YES The page where the cardholder should be redirected when <Cancel> is pressed on the payment page.

URL_Notify http://site.ext/paymentNotify String YES Address supplied by the partner, where the IPGPurchaseNotify API call will send the parameters for the successful payment.

Note String NO Text associated with the purchase.

17

CartItems 2 Int YES The number of rows (items) in the logical record Cart. If there will be some additional fees/taxes for the cardholder, they need to be added as new items.

Cart Logical Holder Logical Record

YES Array provided by the Merchant. The array describes the content of the shopping cart. The content will be displayed on the IPG payment page.

CardholderName John Smith String YES Name of the cardholder

Email [email protected] String YES This is the cardholder’s email.

MobileNumber +359811222111 String NO Cardholder’s mobile number

BillAddrCountry 100 String (3)

YES ISO 3166-1 numeric three-digit country code of the customer’s billing country.

BillAddrCity Sofia String (50)

YES Customer’s billing city.

BillAddrPostCode 1421 String (16)

YES Customer’s billing ZIP code.

BillAddrState 22 String (3)

No Country subdivision code defined in ISO 3166-2

BillAddrLine1 128 Dondukov Blvd String (50)

YES Billing Address Line 1

BillAddrLine2 String (50)

NO Billing Address Line 2



ShipAddrCountry 100 String (3)

NO ISO 3166-1 numeric three-digit country code of customer’s shipping country.

ShipAddrCity String (50)

NO Customer’s shipping city.

ShipAddrPostCode String (16)

NO Customer’s shipping ZIP code.

18

ShipAddrState String (3)

NO Country subdivision code defined in ISO 3166-2

ShipAddrLine1 String (50)

NO Shipping Address Line 1





*URL_OK, URL_Cancel and URL_Notify could be the same. IPG will supply the proper method in the property “IPGmethod”. Properties MID in combination with OrderID gives a unique identifier for the request of a partner.

IPG will reject duplicated transmission.

Cart Logical Record

Cart logical record consists of standard POST parameters with the form name=value. For every

consequent item an index is added that shows the logical record number for the item (ex. Atricle_1).

Indexes are from 1 to <CartItems>.

Property Typical

value

Type Description

Article HP ProBook 6360b sticker

String Name of an article in the shopping cart.

Quantity 2 Int How many pieces of an article.

Price 2.34 Double Price of a single unit.

Amount 4.68 Double Quantity*Price for the article.

Currency 978 N(3) Should be the same currency as in the purchase amount.


Example

New lines and tabulators are included for better reading and do not exist in the POST request.

IPGmethod=IPGPurchase&

KeyIndex=1&

BannerIndex=1&

IPGVersion=3.3&

Language=en&

Originator=33&

MID=000000000000123&

MIDName=Example Web Shop Name&

Amount=23.45&

Currency=978&

CustomerIP=82.119.81.30&

OrderID=1854&

OrderLink=http://site.ext&

URL_OK=http://site.ext/paymentOK&

URL_Cancel=http://site.ext/paymentNOK&

19

URL_Notify=http://site.ext/paymentNotify&

Note=note&

CardholderName= John Smith& [email protected]&

BillAddrCountry=100&

BillAddrCity=Sofia&

BillAddrPostCode=1421&

BillAddrLine1= 128 Dondukov Blvd& CartItems=2&

Article_1=HP ProBook 6360b sticker&

Quantity_1=2&

Price_1=2.34&

Amount_1=4.68&

Currency_1=978&


Quantity_2=1&

Price_2=2.00&

Amount_2=2.00&

Currency_2=978&

Signature=s2xNbaqKS5wrcXY/cguip4S/+UQZZkeeXC4Gg3gbn/Gh5KNI/DDyD2xVpfr

sjhX6XV/N4922yIJOB74ni374AR176gF4+bpgMWIiVbjR2OS2FFMXJcC0JJpEcqKcDcjjH4cS7l

2Obnr3JUsOC45iabTd6G/e722aiwvAmJtcqSo=

Processing MOTO transaction by Merchant (API call: IPGMoto)

Purpose

This method is used by IPG to allow merchant to process MOTO transactions. Merchant is placed on

a page that requests entering payment card details. The Merchant could decide whether or not to

use this method.

IPG will check:

• Valid MID.


Method properties






20









*URL_OK, URL_Cancel and URL_Notify could be the same. IPG will supply the proper method in the property “IPGmethod”.

Properties MID in combination with OrderID gives a unique identifier for the request of a

partner. IPG will reject duplicated transmission.

Example


IPGmethod=IPGMoto&

KeyIndex=1&

BannerIndex=1&

IPGVersion=3.3&

Language=en&

Originator=33&

21

MID=112&


Amount=40&

Currency=978&


OrderID=1426924312&

OrderLink=&

URL_OK=http://site.ext/paymentOK&



Note=Something&

Signature=R2HaW8BYVClUmo9z8h2RaJqhXAHD3CuOLpINkgGFIsJfZL+NxtAj8eeA5Mf

26LXEaVqu/jdArCPdv1N8bg70ulNV5S2+HIpfpV5ctzBEwHu+pPNhz0M73G/HPU8Hgf0BSSf1pX

YjLgaWB1p3gebaIXXjblz9rPax//eAt74M+BA=

First recurring transaction with payment card (API call: IPGFirstRecurring)

Purpose

This method is used by IPG to allow cardholder to make first payment transaction in a subscription

(recurring agreement). Cardholder is placed on a page that requests entering payment card details.

The Merchant could decide whether or not to use this method.

IPG will check:

• Valid MID.


Method properties






22


OrderID 201203319999999 String YES Placeholder for the merchant. Used to put some data that will help the merchant to recognize for which order or subscription is the payment. Up to 255 characters.






23


CardholderName John Smith String YES Name of the cardholder

Email [email protected] String YES This is the customer’s email.

MobileNumber +359811222111 String NO Customer’s mobile number


YES ISO 3166-1 numeric three-digit country code of the customer’s billing country.


YES Customer’s billing city.


YES Customer’s billing ZIP code.


No Country subdivision code defined in ISO 3166-2


YES Billing Address Line 1




















Properties MID in combination with OrderID gives a unique identifier for the request of a

partner. IPG will reject duplicated transmission.

24

Example


IPGmethod=IPGFirstRecurring&

IPGVersion=3.3&

Language=en&

Originator=33&

KeyIndex=1&

MID=112&


Amount=40&

Currency=978&

CustomerIP=0.0.0.0&

OrderID=1435559739&


BannerIndex=1&

CardholderName=John Smith&

[email protected]&


BillAddrCity=Sofia&


BillAddrLine1= 128 Dondukov Blvd& URL_OK=http://site.ext/paymentOK&



Note=Something&

Signature=kcBs8LoJkXZlclhpykaWIxiDojXH3WFChF5WEx+QkNxOmtYNA9p4PxqanPa

MYUbiuPCKdfE6dQINJt45bNteW/bHpWt5m4CSfUbvGp/ihPV/PVq6XAuu8/SSR4CZhqY6giDfpR

h8Bip67pm2FjRo7Uujw7mZvFdQ5Ye5tEWU5hM=

Processing subsequent recurring transaction by Merchant (API call:

IPGSubsequentRecurring)

Purpose

This method is used by IPG to allow merchant to process subsequent recurring transaction. The IPG

API will return an xml with the result. This method is intended to be utilized by the Merchant in his

website back-end. Merchant is obliged to use this method in case of offering of subscription payments

to clients- cardholders.

IPG will check:

• Valid MID.


mailto:[email protected]&

25

Method properties


MID 000000000000123 AN(15) YES Identifier of the virtual terminal used

for the purchase.

IPG_Trnref 12345678923 String Used to uniquely identify a

transaction in IPG. Used as a

parameter for subsequent recurring

transaction in order to identify first

recurring transaction of subscription.

Amount 23.45 Double YES The amount of the payment

requested.

Currency 978 N(3) YES ISO numeric currency code. The

currency for the payment must be

equal to the currency of the MID.



OutputFormat xml String NO Output format of data. The property

can be “xml” or “json”. If it is not

specified in the request, the default

value is “xml”.

Example of POST request


IPGmethod=IPGSubsequentRecurring&

IPGVersion=3.3&

Language=en&

Originator=33&

KeyIndex=1&

MID=112&

IPG_Trnref=20150623103635576924&

Amount=40&

Currency=978&

OrderID=1435560269&

[email protected]&

OutputFormat=xml&

Signature=T8URqA3gkfrXZ/K1Y+CC1US0pm104Lw92lR5gGfqFK1yBaUB7PfeqTGd/az

IEeQjxN9zYYA/ygkMnzsvTKxE8TiFKteHN4xjykxxTOLaLxwEfBpcNqq+/j55l8sVsAdoM1VBdm

nTK/Q1aiYIJZe3p0/ScFlyMhmmxYG0NAE63dg=

26

Example of the xml

<ipg_responce> <method>IPGSubsecuentRecurring</method> <trnref>123456789</trnref> <trnreforiginal>123456789</trnreforiginal>

<OrderID>XXXXXX</OrderID> <status>0</status> <status_msg>Success</status_msg>

</ipg_responce>

Successful payment notification (API call: IPGPurchaseNotify / IPGPurchaseOK)

Purpose

This method is used by IPG to notify the merchant for a successful payment and to pass all needed

parameters for the payment on URL_Notify. After successful response for this method IPG will

redirect the customer browser to URL_OK and will pass same parameters with IPGPurchaseOK

method.

Method properties


MID 000000000000123 AN(15) Echo from IPGPurchase.

Amount 23.45 Double Echo from IPGPurchase.

Currency 978 N(3) Echo from IPGPurchase.

CustomerIP 82.119.81.30 String Echo from IPGPurchase.

OrderID 201203319999999 string Echo from IPGPurchase.

Approval 123456 String Approval code return by the issuer of the card. Used to identify the financial transaction within the card schemes and the issuer.

IPG_Trnref 12345678923 String Used to uniquely identify a transaction in IPG. Used as a parameter for subsequent refund of reversal if needed.

RequestDateTime 2012-03-31 23:59:59 DateTime Date/time of the request

RequestSTAN 123456 N(6) Consequent number from 1 to 999999. Used for request unique match.

Signature Byte[] BASE64 Signed HASH for all properties in the

command. Signature is ALWAYS THE

LAST PARAMETER IN THE POST, as it

is not used to calculate the hash.

Pan 0000 String Last four digits of the account

number (PAN) for the transaction

27

Cancelation of payment notification (API call: IPGPurchaseCancel)

Purpose

This method is used by IPG to notify the merchant that the customer has canceled the payment. IPG

will redirect with this method when the customer choose cancel payment. The call will be made on

previously supplied URL_Cancel.

Method properties








Rollback of previous notification (API call: IPGPurchaseRollback)

Purpose

This method is used by IPG to notify that a reversal is passed for previous successful authorization.

The merchant should mark the order as not paid (in case, the merchant has received

IPGPurchaseNotify method). This is used when IPG do not receive and HTTP OK from the merchant

as a response for IPGPurchaseNotify method. The call will be posted to URL_Notify.

Method properties








28

Get transaction status for previously executed payment (API call:

IPGGetTxnStatus)

Purpose

This method is used by Merchant to get the current status of previously executed payment. The IPG

API will return an xml with information about a specific OrderID. This method is intended to be utilized

by the Merchant in his website back-end. The Merchant could decide whether or not to use this

method.

Possible statuses are:

IPG Response

IPG Response Description

100 Transaction completed successful

1 Pending - Transaction rejected by payment gateway - Technical issue

2 Pending - Transaction rejected by payment gateway - Invalid request

3 Pending - Transaction rejected by payment gateway - Risk assessment

4 Pending - Rejected by the issuer

5 Pending - Rejected by the issuer - Insuficient funds

6 Pending - Rejected by the issuer - Risk assessment

7 Pending - Rejected by the issuer - Invalid card

8 Pending - Rejected by the issuer - Invalid amaount

9 Pending - Rejected by the issuer - Failed 3DS

10 Transaction rejected by payment gateway - Technical issue

11 Transaction rejected by payment gateway - Invalid request

12 Transaction rejected by payment gateway - Risk assessment

13 Rejected by the issuer

14 Rejected by the issuer - Insuficient funds

15 Rejected by the issuer - Risk assessment

16 Rejected by the issuer - Invalid card

17 Rejected by the issuer - Invalid amaount

18 Rejected by the issuer - Failed 3DS

19 User input time out - Payment page or 3DS at Issuer

20 Pending - No customer input or 3DS response

21 Canceled by the customer - No 3DS response

97 Reversed

98 Internal Error

99 Not Found

29

Method properties




OutputFormat xml String NO Output format of data. The property can be “xml” or “json”. If it is not specified in the request, the default value is “xml”.

Example of the xml

<?xml version="1.0"?>

<ipg_responce>

<method>IPGGetTxnStatus</method>

<order_id>XXXXXX</order_id>

<status>0</status>

<status_msg>Success</status_msg>

<MID>000000000000112</MID>

<Amount>20</Amount>

<Currency>978</Currency>

<OrderID>1591703347</OrderID>

<Approval>MCQSIM</Approval>

<IPG_Trnref>20200609114915334253</IPG_Trnref>

<IPG_TrnStatus>1</IPG_TrnStatus>

<IPG_TrnStatusMsg>Approved</IPG_TrnStatusMsg>

<Signature>

nEd9SdLSSMI+nmxQx7Mfk4MlM9D3JeJBFWJxAq39pLsDD1mH5o/Ll74pIiq/+1xhjxwprJjUZqy

393JDs9CfRFGQifoJoRwnWn0Ux39ldfPMt0oCtv2AObJ3QJcq8OGCAblDBnYKFI6NjvH9jVA+BW

KA9maUU3+vF3fdiU2JB/U=

</Signature>

</ipg_responce>

Make a refund for previously executed payment (API call: IPGRefund)

Purpose

This method is used by Merchant to initiate a refund of previously executed payment. The IPG API will

return an xml with the result. This method is intended to be utilized by the Merchant in his website

back-end. The Merchant could decide whether or not to use this method.

Method properties



30

IPG_Trnref 12345678923 String YES Used to uniquely identify a transaction in IPG. Used as a parameter for subsequent refund of reversal if needed.



OutputFormat xml String NO Output format of data. The property can be “xml” or “json”. If it is not specified in the request, the default value is “xml”.

Example of the xml

<ipg_responce> <method>IPGRefund</method> <trnref>12345667</trnref> <amount>0.1</amount> <currency>978</currency> <status>0</status> <status_msg>Success</status_msg>

</ipg_responce>

Make a reversal for previously executed payment (API call: IPGReversal)

Purpose

This method is used by Merchant to initiate a reversal of previously executed payment. The IPG API

will return an xml with the result. This method is intended to be utilized by the Merchant in his

website back-end. The Merchant could decide whether or not to use this method.

Method properties


IPG_Trnref 12345678923 String Yes Used to uniquely identify a transaction in IPG. Used as a parameter for subsequent refund of reversal if needed.

OutputFormat xml String No Output format of data. The property can be “xml” or “json”. If it is not specified in the request, the default value is “xml”.

Example of the xml

<ipg_responce> <method>IPGReversal</method>

31

<trnref>123456789</trnref> <status>0</status> <status_msg>Success</status_msg>

</ipg_responce>

Store card (API call: IPGStoreCard)

Purpose

This method is used by IPG to allow saving of a card. Cardholder is placed on a page that requests

entering payment card details. The command returns a Token which can be used later for performing

Payments with stored card. The Merchant could decide whether or not to use this method.

To verify the card a transaction with zero amount is sent. As a result of execution of IPGStoreCard IPG

will send any of the following notifications:

• IPGStoreCardOK – Verification transaction is approved. Card is confirmed and saved.

• IPGStoreCardCancel – User clicks Cancel. No card is saved.

IPG will check:

• Valid MID.


• Properties MID in combination with OrderID gives a unique identifier for the request

of a partner. IPG will reject duplicated transmission.

Method properties


MID 000000000000123 AN(15) YES Identifier of the virtual terminal used for storing the card.

MIDName Merchant Web Shop String YES User friendly name of the merchant web shop. The cardholder will see this name on some notices in the page.

OrderID 201203319999999 String YES Placeholder for the merchant. Used to put some data that will help the merchant to uniquely identify the request.

32

Currency 978 N(3) YES ISO numeric currency code. The currency must be equal to the currency of the MID.








CardholderName John Smith String YES Customer’s first name.

MobileNumber +359811222111 String NO Customer’s mobile number

33


NO ISO 3166-1 numeric three-digit country code of the customer’s billing country.


NO Customer’s billing city.


NO Customer’s billing ZIP code.
























Example


IPGmethod=IPGStoreCard&

IPGVersion=3.3&

Language=en&

Originator=33&

KeyIndex=1&

MID=112&


Currency=978&

CustomerIP=0.0.0.0&

OrderID=1435559739&

34

BannerIndex=1&


[email protected]&


BillAddrCity=Sofia&


BillAddrLine1= 128 Dondukov Blvd& URL_OK=http://site.ext/paymentOK&



Note=Something&

Signature=kcBs8LoJkXZlclhpykaWIxiDojXH3WFChF5WEx+QkNxOmtYNA9p4PxqanPa

MYUbiuPCKdfE6dQINJt45bNteW/bHpWt5m4CSfUbvGp/ihPV/PVq6XAuu8/SSR4CZhqY6giDfpR

h8Bip67pm2FjRo7Uujw7mZvFdQ5Ye5tEWU5hM=

Store Card Success Notification (API call: IPGStoreCardOK)

Purpose

This method is used by IPG to notify the merchant for a successful storing of a card and to pass all

needed parameters for subsequent transaction on URL_Notify. After successful response for this

method IPG will redirect the customer browser to URL_OK and will pass the following parameters.

Method properties


MID 000000000000123 AN(15) Echo from IPGStoreCard.

Token D747458899D….FC43D5 String(64) Token of the card used for subsequent payments.

PAN ****4985 Last 4 digits of PAN.

Currency 978 N(3) Echo from IPGStoreCard.

CustomerIP 82.119.81.30 String Echo from IPGStoreCard.

OrderID 201203 string Echo from IPGStoreCard.

CardType VISA String The brand of the card – MasterCard, VISA, JCB, etc.

CardholderName Rayna Lazarova The name on card.

CustomName My VISA card from iCard. Custom name under which the card is stored.

Approval 123456 String To verify the card a transaction with zero amount is performed. As a result Approval code is return by the issuer of the card. Used to identify the financial transaction within the card schemes and the issuer.

IPG_Trnref 12345678923 String Used to uniquely identify a transaction in IPG. Used as a parameter for subsequent refund of reversal if needed.

RequestDateTime 2012-03-31 23:59:59 DateTime Date/time of the request

RequestSTAN 123456 N(6) Consequent number from 1 to 999999. Used for request unique match.

35

Signature Byte[] BASE64 Signed HASH for all properties in the

command. Signature is ALWAYS THE

LAST PARAMETER IN THE POST, as it

is not used to calculate the hash.

Store Card Cancelation Notification (API call: IPGStoreCardCancel)

Purpose

This method is used by IPG to notify the merchant that the customer has canceled the storing of a card.

IPG will redirect with this method when the customer choose cancel. The call will be made on

previously supplied URL_Cancel.

Method properties


MID 000000000000123 AN(15) Echo from IPGStoreCard.

Currency 978 N(3) Echo from IPGStoreCard.

OrderID 201203319999999 string Echo from IPGStoreCard.

CustomerIP 82.119.81.30 String Echo from IPGStoreCard.


Purchase with stored card (API call: IPGPurchaseWithStoredCard)

Purpose

This method is used by IPG to allow merchant to process subsequent recurring transaction. The IPG

API will return an xml with the result. This method is intended to be utilized by the Merchant in his

website back-end. Merchant is obliged to use this method in case of offering of subscription payments

to clients- cardholders.

IPG will check:

• Valid MID.


36

Method properties


MID 000000000000123 AN(15) YES Identifier of the virtual

terminal used for the

purchase.

Currency 978 N(3) YES ISO numeric currency code.

The currency for the payment

must be equal to the currency

of the MID.


Token gqGCQBw9KDsoIq...AwmI String YES Token of the card. It should be encrypted with iCARD public key with padding PKCS1.


requested.

OutputFormat xml String NO Output format of data. The

property can be “xml” or

“json”. If it is not specified in

the request, the default value

is “xml”.



IPGmethod=IPGPurchaseWithStoredCard&

IPGVersion=3.3&

Language=en&

Originator=33&

KeyIndex=1&

MID=112&

Currency=978&

OrderID=1435560269&

Token= gqGCQBw9KDsoIq...AwmI Amount=40&

OutputFormat=xml&




Example of the xml

<ipg_responce>

37

<method>IPGPurchaseWithStoredCard</method> <IPG_Trnref>123456789</IPG_Trnref> <Approval>123456789</Approval> <OrderID>XXXXXX</OrderID> <status>0</status> <status_msg>Success</status_msg>

</ipg_responce>

Processing Original Credit Transaction (OCT) (API call: IPGOCT)

Purpose

This method is used by IPG to allow merchant to process OCT transaction. OCT transactions are used

for Gaming Repay or sending money from Merchant to Customer.

This method is intended to be utilized by the Merchant in his website back-end. IPG API will return an

xml with the result. The request can be initialized only by a reference from a previously executed

payment transaction.

IPG will check:

• Valid MID.


Method properties


MID 000000000000123 AN(15) YES Identifier of the virtual terminal

used for the purchase.

IPG_Trnref 12345678923 String Used to uniquely identify a

transaction in IPG. Used as a

parameter for subsequent

recurring transaction in order to

identify first recurring transaction

of subscription.


requested.

Currency 978 N(3) YES ISO numeric currency code. The

currency for the payment must be

equal to the currency of the MID.


38

PaymentProgram 0 N(2) No Defines the payment program

0 = GamblingRepay (Default)

1 = BusinessToCustomer

When this parameter is missing

GamblingRepay is set by default.

Allowed Payment programs should

be configured by iCard

representative.

OutputFormat xml String NO Output format of data. The

property can be “xml” or “json”. If

it is not specified in the request,

the default value is “xml”.



IPGmethod=IPGOCT&

IPGVersion=3.3&

Language=en&

Originator=33&

KeyIndex=1&

MID=112&

IPG_Trnref=20150623103635576924&

Amount=40&

Currency=978&

OrderID=1435560269&

PaymentProgram=0&

OutputFormat=xml&




Example of the xml

<ipg_responce> <method>IPGOCT</method> <trnref>123456789</trnref> <trnreforiginal>123456789</trnreforiginal> <status>0</status> <status_msg>Success</status_msg>

</ipg_responce>

39

IPG Payment Widget IPG Payment widget is piece of code that can be embed right on to Web page of store. It works like a

mini-application that is used to collect payment data and process transaction. Widget allows

processing without redirects which finally improves user experience, increases level of trust and

comforts end customers.

IPG Widget process

iPG Widget

iPG (iCard)Merchant iPG Widget (iCard)

Requests token per transactions

Generates token

Places token in Java script code,

embedded in HTML of own site

Widget generation

Cardholder enters card data and

confirm transactionProcess transaction

Confirms with URL OK

Successful payment (success page)

Notifies Merchant on Notify URL sent

with Token Request

Picture 1

Processing of transaction with IPG Widget is shown on Picture 1.

Payment Token Request (API Call: IPGPaymentToken)

Purpose

Payment Token Request is a back-end synchronous request. Merchant’ system sends all required

information about payment transaction. In response is received token, which must be used in next

step.

40

Method properties

Method properties required too (check page 12)


WidgetType IPGPurchase

String Yes Type of payment method which will be run in widget. Possible values are:

- IPGPurchase - IPGFirstRecurring - IPGMoto - IPGStoreCard

All other required parameters depend on selected WidgetType value. They are described in documentation and could be found after following the links below:

- IPGPurchase - IPGFirstRecurring - IPGMoto - IPGStoreCard

Note: URL_Cancel and URL_OK which are mandatory in original methods (IPGPurchase, IPGFirstRecurring, IPGMoto and IPGStoreCard) are not required with IPGPaymentTokenRequest.



WidgetType=IPGPurchase

MID=000000000000123&


Amount=23.45&

Currency=978&


OrderID=1854&


BannerIndex=1&


Note=note&


[email protected]&


BillAddrCity=Sofia&


BillAddrLine1= 128 Dondukov Blvd& CartItems=2&


Quantity_1=2&

Price_1=2.34&

Amount_1=4.68&

Currency_1=978&


Quantity_2=1&

Price_2=2.00&

Amount_2=2.00&

Currency_2=978

41

Example of xml

<ipg_responce> <status>0</status> <status_msg>Success</status_msg> <token>7bdf3e9b371abe470c1e6a8073c82dbe9ef1d155</token> <Signature>cxhmU3IhvcobGAGKiCLZbOjqRtykAFyEtEefrzWGdsfBEGohlUelPOeBZXfVfmtgcWk9hoWqjQYkaNK6mjvhHZLwTS0IBAmrut6/COVS7Ryv1qkf1Icbd7mFBW8UaEeHHz9ujB+/nlKJ/R5K83d9Vrvwnj8PKVwk4MnNAYQtg3Q=</Signature> </ipg_responce>

Create payment form

In order to create the payment form, Merchant just needs to add the following lines of HTML/JavaScript to own page and populating the placeholders where widget will be displayed.

Wrapper

Wrapper MUST have id=” ipg”. Following tag should be added to HTML code of Merchant’s site: <div id="ipg"></div>

Wrapper customization

Merchant can set inline styles. For example: Default minimum width is 320px. Below is provided an example how it could be changed: <div style="width: 400px; height: 600px">

<div id="ipg"></div> </div>

JavaScript code

Following JavaScript code should be added to Merchant’s website. Placeholder “_TOKEN_ “must be replaced with token value, obtained on step 1 as response of API Call IPGPaymentTokenRequest. Below code should be placed right before </body> tag: <script>

!function (d, s, id) {

var js, fjs = d.getElementsByTagName(s)[0];

if (!d.getElementById(id)) {

js = d.createElement(s);

js.id = id;

42

js.src = "https://ipg.icard.com/js/payment-

widget.js?token=_TOKEN_";

fjs.parentNode.insertBefore(js, fjs);

}

}(document, "script", "ipg-io-js");

</script>

After successful payment, Merchant system will receive asynchronous request to URL_Notify (same

which was provided with API Call IPGPaymentTokenRequest on step 1) with details.

Widget customization

Merchant can set custom styles of whole widget and payment button. Below is provided an example: <script>

var ipgPaymentOptions = {

styles: '' +

'#ipgControlPay {background-color: #000000} ' +

'#ipgControlPay:hover {background-color: #c3c3c3} ' +

'#ipgForm {background-color: #00A000; color: #fff}',

};

!function (d, s, id) {

var js, fjs = d.getElementsByTagName(s)[0];

if (!d.getElementById(id)) {

43

Appendix I – Error messages

Status code

Status message Description

0 Success

1 E_MISSING_REQ_PARAMS Some of required fields from the POST request are missing.

2 E_SIGNATURE_FAILED The parameter ‘Signature’ is not correct.

3 E_INTERNAL_ERROR Invalid or missing response from IPG servers. Please contact IPG engineers.

4 E_INVALID_MID The MID is not valid.

5 E_INVALID_PARAMS One or more of the other parameters from the POST request are not correct.

6 E_INVALID_REFERER Invalid Referrer

7 E_PAYMENT_TRIES Payment tries limit exceed

8 E_TRANSACTION_AUTH_FAIL Authorization failure. Transaction is decline.

9 E_ORIG_TX_NOT_FOUND Original transaction not found

99 E_UNDEFINED_ERROR Other unspecified error.

Note:

These error messages will be visible on the payment page only in test environment. In production

environment the cardholder will see an error page with the following text:

You are not able to proceed with the payment process. Some of required information is missing. Please try again. << Return to [MIDName]

Documents

Accepting e-commerce payments for merchants