View
2
Download
0
Category
Preview:
Citation preview
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
Method properties ............................................................................................................ 19
Example ............................................................................................................................. 20
3
First recurring transaction with payment card (API call: IPGFirstRecurring) ....................... 21
Purpose ............................................................................................................................. 21
Method properties ............................................................................................................ 21
Example ............................................................................................................................. 24
Processing subsequent recurring transaction by Merchant (API call:
IPGSubsequentRecurring) ..................................................................................................... 24
Purpose ............................................................................................................................. 24
Method properties ............................................................................................................ 25
Example of POST request .................................................................................................. 25
Example of the xml ........................................................................................................... 26
Successful payment notification (API call: IPGPurchaseNotify / IPGPurchaseOK) ............... 26
Purpose ............................................................................................................................. 26
Method properties ............................................................................................................ 26
Cancelation of payment notification (API call: IPGPurchaseCancel) .................................... 27
Purpose ............................................................................................................................. 27
Method properties ............................................................................................................ 27
Rollback of previous notification (API call: IPGPurchaseRollback) ....................................... 27
Purpose ............................................................................................................................. 27
Method properties ............................................................................................................ 27
Get transaction status for previously executed payment (API call: IPGGetTxnStatus) ....... 28
Purpose ............................................................................................................................. 28
Method properties ............................................................................................................ 29
Example of the xml ........................................................................................................... 29
Make a refund for previously executed payment (API call: IPGRefund) .............................. 29
Purpose ............................................................................................................................. 29
Method properties ............................................................................................................ 29
4
Example of the xml ........................................................................................................... 30
Make a reversal for previously executed payment (API call: IPGReversal) .......................... 30
Purpose ............................................................................................................................. 30
Method properties ............................................................................................................ 30
Example of the xml ........................................................................................................... 30
Store card (API call: IPGStoreCard) ....................................................................................... 31
Purpose ............................................................................................................................. 31
Method properties ............................................................................................................ 31
Example ............................................................................................................................. 33
Store Card Success Notification (API call: IPGStoreCardOK) ................................................ 34
Purpose ............................................................................................................................. 34
Method properties ............................................................................................................ 34
Store Card Cancelation Notification (API call: IPGStoreCardCancel) ................................... 35
Purpose ............................................................................................................................. 35
Method properties ............................................................................................................ 35
Purchase with stored card (API call: IPGPurchaseWithStoredCard) .................................... 35
Purpose ............................................................................................................................. 35
Method properties ............................................................................................................ 36
Example of POST request .................................................................................................. 36
Example of the xml ........................................................................................................... 36
Processing Original Credit Transaction (OCT) (API call: IPGOCT) ......................................... 37
Purpose ............................................................................................................................. 37
Method properties ............................................................................................................ 37
Example of POST request .................................................................................................. 38
Example of the xml ........................................................................................................... 38
IPG Payment Widget ................................................................................................................ 39
5
IPG Widget process ............................................................................................................... 39
Payment Token Request (API Call: IPGPaymentToken) ....................................................... 39
Purpose ............................................................................................................................. 39
Method properties ............................................................................................................ 40
Example of POST request .................................................................................................. 40
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
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
Authorization system
processes payment
Press PAY
Is The Card 3D
secure enebled
NOIs 3D
authentication
Successfull
YES
Transaction Result from
Authorization system
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 name@website.com 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
BillAddrLine3 String (50)
NO Billing Address Line 3
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
ShipAddrLine2 String (50)
NO Shipping Address Line 2
ShipAddrLine3 String (50)
NO Shipping Address Line 3
*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.
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.
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=john.smith@website.com&
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&
Article_2=HP ProBook 6360b sticker&
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.
• 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.
20
CustomerIP 82.119.81.30 String YES Dotted-decimal string, that holds the customer IP address as reported at merchant web shop.
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.
*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
New lines and tabulators are included for better reading and do not exist in the POST request.
IPGmethod=IPGMoto&
KeyIndex=1&
BannerIndex=1&
IPGVersion=3.3&
Language=en&
Originator=33&
21
MID=112&
MIDName=Example Web Shop Name&
Amount=40&
Currency=978&
CustomerIP=82.119.81.30&
OrderID=1426924312&
OrderLink=&
URL_OK=http://site.ext/paymentOK&
URL_Cancel=http://site.ext/paymentNOK&
URL_Notify=http://site.ext/paymentNotify&
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.
• 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.
22
CustomerIP 82.119.81.30 String YES Dotted-decimal string, that holds the customer IP address as reported at merchant web shop.
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.
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.
23
Note String NO Text associated with the purchase.
CardholderName John Smith String YES Name of the cardholder
Email name@website.com String YES This is the customer’s email.
MobileNumber +359811222111 String NO Customer’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
BillAddrLine3 String (50)
NO Billing Address Line 3
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.
ShipAddrState String (3)
NO Country subdivision code defined in ISO 3166-2
ShipAddrLine1 String (50)
NO Shipping Address Line 1
ShipAddrLine2 String (50)
NO Shipping Address Line 2
ShipAddrLine3 String (50)
NO Shipping Address Line 3
*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.
24
Example
New lines and tabulators are included for better reading and do not exist in the POST request.
IPGmethod=IPGFirstRecurring&
IPGVersion=3.3&
Language=en&
Originator=33&
KeyIndex=1&
MID=112&
MIDName=Example Web Shop Name&
Amount=40&
Currency=978&
CustomerIP=0.0.0.0&
OrderID=1435559739&
OrderLink=http://site.ext&
BannerIndex=1&
CardholderName=John Smith&
Email=name@website.com&
BillAddrCountry=100&
BillAddrCity=Sofia&
BillAddrPostCode=1421&
BillAddrLine1= 128 Dondukov Blvd& URL_OK=http://site.ext/paymentOK&
URL_Cancel=http://site.ext/paymentNOK&
URL_Notify=http://site.ext/paymentNotify&
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.
• Valid currency with regards to the MID.
25
Method properties
Property Typical value Type Required Description
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.
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.
Email name@website.com String YES This is the cardholder’s email.
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
New lines and tabulators are included for better reading and do not exist in the 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=name@website.com&
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
Property Typical value Type Description
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
Property Typical value Type Description
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.
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.
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
Property Typical value Type Description
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.
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.
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
Property Typical value Type Required Description
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.
MID 000000000000123 AN(15) YES Identifier of the virtual terminal used for the purchase.
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
Property Typical value Type Required Description
MID 000000000000123 AN(15) YES Identifier of the virtual terminal used for the purchase.
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.
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 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
Property Typical value Type Required Description
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.
• Valid currency with regards to the MID.
• Properties MID in combination with OrderID gives a unique identifier for the request
of a partner. IPG will reject duplicated transmission.
Method properties
Property Typical value Type Required Description
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.
CustomerIP 82.119.81.30 String YES Dotted-decimal string, that holds the customer IP address as reported at merchant web shop.
Email name@website.com String YES This is the cardholder’s email.
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.
CardholderName John Smith String YES Customer’s first name.
MobileNumber +359811222111 String NO Customer’s mobile number
33
BillAddrCountry 100 String (3)
NO ISO 3166-1 numeric three-digit country code of the customer’s billing country.
BillAddrCity Sofia String (50)
NO Customer’s billing city.
BillAddrPostCode 1421 String (16)
NO Customer’s billing ZIP code.
BillAddrState 22 String (3)
NO Country subdivision code defined in ISO 3166-2
BillAddrLine1 128 Dondukov Blvd String (50)
NO Billing Address Line 1
BillAddrLine2 String (50)
NO Billing Address Line 2
BillAddrLine3 String (50)
NO Billing Address Line 3
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.
ShipAddrState String (3)
NO Country subdivision code defined in ISO 3166-2
ShipAddrLine1 String (50)
NO Shipping Address Line 1
ShipAddrLine2 String (50)
NO Shipping Address Line 2
ShipAddrLine3 String (50)
NO Shipping Address Line 3
*URL_OK, URL_Cancel and URL_Notify could be the same. IPG will supply the proper method in the property “IPGmethod”.
Example
New lines and tabulators are included for better reading and do not exist in the POST request.
IPGmethod=IPGStoreCard&
IPGVersion=3.3&
Language=en&
Originator=33&
KeyIndex=1&
MID=112&
MIDName=Example Web Shop Name&
Currency=978&
CustomerIP=0.0.0.0&
OrderID=1435559739&
34
BannerIndex=1&
CardholderName=John Smith&
Email=name@website.com&
BillAddrCountry=100&
BillAddrCity=Sofia&
BillAddrPostCode=1421&
BillAddrLine1= 128 Dondukov Blvd& URL_OK=http://site.ext/paymentOK&
URL_Cancel=http://site.ext/paymentNOK&
URL_Notify=http://site.ext/paymentNotify&
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
Property Typical value Type Description
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
Property Typical value Type Description
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.
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.
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.
• Valid currency with regards to the MID.
36
Method properties
Property Typical value Type Required Description
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.
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.
Token gqGCQBw9KDsoIq...AwmI String YES Token of the card. It should be encrypted with iCARD public key with padding PKCS1.
Amount 23.45 Double YES The amount of the payment
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”.
Example of POST request
New lines and tabulators are included for better reading and do not exist in the POST request.
IPGmethod=IPGPurchaseWithStoredCard&
IPGVersion=3.3&
Language=en&
Originator=33&
KeyIndex=1&
MID=112&
Currency=978&
OrderID=1435560269&
Token= gqGCQBw9KDsoIq...AwmI Amount=40&
OutputFormat=xml&
Signature=T8URqA3gkfrXZ/K1Y+CC1US0pm104Lw92lR5gGfqFK1yBaUB7PfeqTGd/az
IEeQjxN9zYYA/ygkMnzsvTKxE8TiFKteHN4xjykxxTOLaLxwEfBpcNqq+/j55l8sVsAdoM1VBdm
nTK/Q1aiYIJZe3p0/ScFlyMhmmxYG0NAE63dg=
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.
• 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.
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.
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.
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”.
Example of POST request
New lines and tabulators are included for better reading and do not exist in the POST request.
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&
Signature=T8URqA3gkfrXZ/K1Y+CC1US0pm104Lw92lR5gGfqFK1yBaUB7PfeqTGd/az
IEeQjxN9zYYA/ygkMnzsvTKxE8TiFKteHN4xjykxxTOLaLxwEfBpcNqq+/j55l8sVsAdoM1VBdm
nTK/Q1aiYIJZe3p0/ScFlyMhmmxYG0NAE63dg=
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)
Property Typical value Type Required Description
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.
Example of POST request
New lines and tabulators are included for better reading and do not exist in the POST request.
WidgetType=IPGPurchase
MID=000000000000123&
MIDName=Example Web Shop Name&
Amount=23.45&
Currency=978&
CustomerIP=82.119.81.30&
OrderID=1854&
OrderLink=http://site.ext&
BannerIndex=1&
URL_Notify=http://site.ext/paymentNotify&
Note=note&
CardholderName=John Smith&
Email=name@website.com&
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&
Article_2=HP ProBook 6360b sticker&
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]
Recommended