ProductsDeveloperSupport
Guides

Recurring Payments

Suggest Edits

Recurring Payments (Merchant Managed)

Recurring FIRST

The following XML document represents an example of a first Sale transaction of a series of recurring payments:

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope
    xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
    <SOAP-ENV:Header/>
    <SOAP-ENV:Body>
        <ns4:IPGApiOrderRequest
            xmlns:ns4="http://ipg-online.com/ipgapi/schemas/ipgapi"
            xmlns:ns2="http://ipg-online.com/ipgapi/schemas/v1"
            xmlns:ns3="http://ipg-online.com/ipgapi/schemas/a1">
            <ns2:Transaction>
                <ns2:CreditCardTxType>
                    <ns2:StoreId>1109950006</ns2:StoreId>
                    <ns2:Type>sale</ns2:Type>
                </ns2:CreditCardTxType>
                <ns2:CreditCardData>
                    <ns2:CardNumber>52392*****0002</ns2:CardNumber>
                    <ns2:ExpMonth>12</ns2:ExpMonth>
                    <ns2:ExpYear>27</ns2:ExpYear>
                    <ns2:CardCodeValue>XXX</ns2:CardCodeValue>
                </ns2:CreditCardData>                
   			 						<ns2:recurringType>FIRST</ns2:recurringType>
                <ns2:Payment>
                    <ns2:ChargeTotal>13.99</ns2:ChargeTotal>
                    <ns2:Currency>978</ns2:Currency>
                </ns2:Payment>
            </ns2:Transaction>
        </ns4:IPGApiOrderRequest>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

In case you have received SchemeTransactionId in the response from the Gateway you should use its value in the subsequent RecurringType=REPEAT request: 

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
   <SOAP-ENV:Header/>
   <SOAP-ENV:Body>
      <ipgapi:IPGApiOrderResponse xmlns:a1="http://ipg-online.com/ipgapi/schemas/a1" xmlns:ipgapi="http://ipg-online.com/ipgapi/schemas/ipgapi" xmlns:v1="http://ipg-online.com/ipgapi/schemas/v1">         <ipgapi:ApprovalCode>Y:403939:4566959508:YYYM:441809</ipgapi:ApprovalCode>
<ipgapi:AVSResponse>YYY</ipgapi:AVSResponse>
<ipgapi:Brand>MASTERCARD</ipgapi:Brand>         <ipgapi:CommercialServiceProvider>BOSMS</ipgapi:CommercialServiceProvider>
<ipgapi:OrderId>A-b64adf8c-8fe8-44cb-97de-fd721033da2e</ipgapi:OrderId>
<ipgapi:IpgTransactionId>84566959508</ipgapi:IpgTransactionId>
<ipgapi:PaymentType>CREDITCARD</ipgapi:PaymentType>
<ipgapi:ProcessorApprovalCode>403939</ipgapi:ProcessorApprovalCode>
<ipgapi:ProcessorCCVResponse>M</ipgapi:ProcessorCCVResponse>
<ipgapi:ProcessorReferenceNumber>119509441809</ipgapi:ProcessorReferenceNumber>
<ipgapi:ProcessorResponseCode>00</ipgapi:ProcessorResponseCode>
<ipgapi:ProcessorResponseMessage>Function performed error-free</ipgapi:ProcessorResponseMessage>
<ipgapi:SchemeTransactionId>0714MCC417474</ipgapi:SchemeTransactionId>
<ipgapi:TDate>1626255235</ipgapi:TDate>
<ipgapi:TDateFormatted>2021.07.14 11:33:55 (CEST)</ipgapi:TDateFormatted>
<ipgapi:TerminalID>80000860</ipgapi:TerminalID>
<ipgapi:TransactionResult>APPROVED</ipgapi:TransactionResult>
<ipgapi:TransactionTime>1626255235</ipgapi:TransactionTime>
</ipgapi:IPGApiOrderResponse>
   </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Recurring REPEAT

Subsequent transactions in a series need to be flagged like this and submitted with the SchemeTransactionId you have received in the previous step. For this purpose you can use the field ReferencedSchemeTransactionId.

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope
    xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
    <SOAP-ENV:Header/>
    <SOAP-ENV:Body>
        <ns4:IPGApiOrderRequest
            xmlns:ns4="http://ipg-online.com/ipgapi/schemas/ipgapi"
            xmlns:ns2="http://ipg-online.com/ipgapi/schemas/v1"
            xmlns:ns3="http://ipg-online.com/ipgapi/schemas/a1">
            <ns2:Transaction>
                <ns2:CreditCardTxType>
                    <ns2:StoreId>1109950006</ns2:StoreId>
                    <ns2:Type>sale</ns2:Type>
                </ns2:CreditCardTxType>
                <ns2:CreditCardData>
                    <ns2:CardNumber>5239*******002</ns2:CardNumber>
                    <ns2:ExpMonth>12</ns2:ExpMonth>
                    <ns2:ExpYear>22</ns2:ExpYear>
                    <ns2:CardCodeValue>XXX</ns2:CardCodeValue>
                </ns2:CreditCardData>
   		 							<ns2:recurringType>REPEAT</ns2:recurringType>
   		 					<ns2:Payment>
                    <ns2:ChargeTotal>13.99</ns2:ChargeTotal>
                    <ns2:Currency>978</ns2:Currency>
                </ns2:Payment>
                <ns2:TransactionDetails> 
                  <ns2:ReferencedSchemeTransactionId>0714MCC417474</ns2:ReferencedSchemeTransactionId>
   			 </ns2:TransactionDetails>
            </ns2:Transaction>
        </ns4:IPGApiOrderRequest>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Recurring Transaction with 3-D Secure

In case you are impacted with PSD2 mandate for Strong Customer Authentication (SCA) and you are managing recurring payments yourself, you must authenticate the cardholder during initial recurring transaction. In such case you need to include additional parameters in the API request as per scheme requirements.

The following represents an example of recurringType = FIRST request including all mandatory parameters:

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope
    xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
    <SOAP-ENV:Header/>
    <SOAP-ENV:Body>
        <ns4:IPGApiOrderRequest
            xmlns:ns4="http://ipg-online.com/ipgapi/schemas/ipgapi"
            xmlns:ns2="http://ipg-online.com/ipgapi/schemas/v1"
            xmlns:ns3="http://ipg-online.com/ipgapi/schemas/a1">
            <ns2:Transaction>
                <ns2:CreditCardTxType>
                    <ns2:StoreId>1109950006</ns2:StoreId>
                    <ns2:Type>sale</ns2:Type>
                </ns2:CreditCardTxType>
                <ns2:CreditCardData>
                    <ns2:CardNumber>52047******2745</ns2:CardNumber>
                    <ns2:ExpMonth>12</ns2:ExpMonth>
                    <ns2:ExpYear>27</ns2:ExpYear>
                    <ns2:CardCodeValue>XXX</ns2:CardCodeValue>
                </ns2:CreditCardData>
                <ns2:CreditCard3DSecure>
<ns2:AuthenticateTransaction>true</ns2:AuthenticateTransaction>
<ns2:TermUrl>https://test.webshop.com/simulator/secure3d/return</ns2:TermUrl>
<ns2:ThreeDSMethodNotificationURL>https://test/ipgconfirmation/services/secure3ds</ns2:ThreeDSMethodNotificationURL>
<ns2:ThreeDSRequestorChallengeIndicator>04</ns2:ThreeDSRequestorChallengeIndicator>
<ns2:ThreeDSRequestorAuthenticationIndicator>02</ns2:ThreeDSRequestorAuthenticationIndicator>
<ns2:recurringFrequency>30</ns2:recurringFrequency>
<ns2:recurringExpiry>20220525</ns2:recurringExpiry>
   			</ns2:CreditCard3DSecure>
   			 <ns2:recurringType>FIRST</ns2:recurringType>
                <ns2:Payment>
                    <ns2:ChargeTotal>12.99</ns2:ChargeTotal>
                    <ns2:Currency>978</ns2:Currency>
                </ns2:Payment>
            </ns2:Transaction>
        </ns4:IPGApiOrderRequest>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

After this request the transaction processing continues with EMV 3-D Secure flow and authorization is triggered automatically once the authentication has been successfully completed.

📘

In case you have not submitted the elements ‘recurringFrequency’ and ‘recurringExpiry’ the Gateway populates these two elements with default values, e.g. ‘recurringFrequency’ = 1 and ‘recurringExpiry’=99991231.


Recurring Scheduler

The action RecurringPayment allows you to install, modify or cancel periodic payments in a way that subsequent transactions will automatically be triggered by the Gateway.

For every recurring transaction, the Gateway can send a server-to-server transaction notification to a defined Notification URL. Please contact your local support team to get your URL registered for these notifications.

Install Recurring Schedule

The following example shows how to install a monthly credit card payment with 12 executions (InstallmentCount) in 2011 starting on 15 January 2011.
Please note, that the RecurringStartDate will be interpreted based on the timezone Europe/Berlin.

<ns4:IPGApiActionRequest 
xmlns:ns4="http://ipg-online.com/ipgapi/schemas/ipgapi" xmlns:ns2="http://ipg-online.com/ipgapi/schemas/a1" xmlns:ns3="http://ipg-online.com/ipgapi/schemas/v1">
	<ns2:Action>
		<ns2:RecurringPayment>
			<ns2:Function>install</ns2:Function>
			<ns2:RecurringPaymentInformation>
				<ns2:RecurringStartDate>20110115</ns2:RecurringStartDate>
				<ns2:InstallmentCount>12</ns2:InstallmentCount>
				<ns2:InstallmentFrequency>1</ns2:InstallmentFrequency>
				<ns2:InstallmentPeriod>month</ns2:InstallmentPeriod>
			</ns2:RecurringPaymentInformation>
			<ns2:CreditCardData>
				<ns3:CardNumber>4035……4977</ns3:CardNumber>
				<ns3:ExpMonth>12</ns3:ExpMonth>
				<ns3:ExpYear>27</ns3:ExpYear>
				<ns3:CardCodeValue>XXX</ns3:CardCodeValue>
			</ns2:CreditCardData>
			<ns3:Payment>
				<ns3:ChargeTotal>1</ns3:ChargeTotal>
				<ns3:Currency>978</ns3:Currency>
			</ns3:Payment>
		</ns2:RecurringPayment>
	</ns2:Action>
</ns4:IPGApiActionRequest>

If you set the RecurringStartDate to the actual date, the first payment will immediately be initiated. In this case, the payment data will only be stored for future payments if this first payment was succesful/approved.
A start date in the past is not allowed.

The default value for TransactionOrigin is ‘ECI’. If you want to change this value, you can submit a different TransactionOrigin tag in the RecurringPayment tag.

Modify Recurring Schedule

Modifications of an existing Recurring Payment can be initiated using the Order ID:

<ns4:IPGApiActionRequest 
xmlns:ns4="http://ipg-online.com/ipgapi/schemas/ipgapi" xmlns:ns2="http://ipg-online.com/ipgapi/schemas/a1" xmlns:ns3="http://ipg-online.com/ipgapi/schemas/v1">
    <ns2:Action>
        <ns2:RecurringPayment>
            <ns2:Function>modify</ns2:Function>
            <ns2:OrderId>e368a525-173f-4f56-9ae2-beb4023a6993</ns2:OrderId>
            <ns2:RecurringPaymentInformation>
                <ns2:InstallmentCount>999</ns2:InstallmentCount>
            </ns2:RecurringPaymentInformation>
        </ns2:RecurringPayment>
    </ns2:Action>
</ns4:IPGApiActionRequest>

You only need to include the elements that need to be changed. If you change the credit card number, it is also required to include the expiry date, otherwise you can change the expiry date without specifying the credit card number. If you want to change the amount, you also need to include the currency.

It is possible to change the payment method, e. g. from Credit Card to German Direct Debit.

Please note, that due to PSD2 regulation it is not allowed to increase transaction amount for a valid subscription without cardholder’s consent achieved through Strong Customer Authentication (SCA). In case modified transaction amount is higher than in the initial recurring payment, it is highly recommended to cancel the schedule and initiate a new request including SCA to avoid declines by the issuer which would eventually terminate your schedule.

Cancel Recurring Schedule

To cancel a Recurring Payment, you also use the Order ID:

<ns4:IPGApiActionRequest 
xmlns:ns4="http://ipg-online.com/ipgapi/schemas/ipgapi" xmlns:ns2="http://ipg-online.com/ipgapi/schemas/a1" xmlns:ns3="http://ipg-online.com/ipgapi/schemas/v1">
	<ns2:Action>
		<ns2:RecurringPayment>
			<ns2:Function>cancel</ns2:Function>
			<ns2:OrderId>e368a525-173f-4f56-9ae2-beb402</ns2:OrderId>
		</ns2:RecurringPayment>
	</ns2:Action>
</ns4:IPGApiActionRequest>

Action Response

The response for a successful instalment, modification or cancellation contains the value true for the parameter successfully

<ns4:IPGApiActionResponse 
xmlns:ns4="http://ipg-online.com/ipgapi/schemas/ipgapi" xmlns:ns2="http://ipg-online.com/ipgapi/schemas/a1" xmlns:ns3="http://ipg-online.com/ipgapi/schemas/v1">
	<ns4:successfully>true</ns4:successfully>
	<ns4:OrderId> A-eab002b9-5889-9cc9-5bc06b8eaa61</ns4:OrderId>
</ns4:IPGApiActionResponse>

Updated 3 months ago

API Products

Point of Sale

Developer

Resources

Contact Cookies Privacy Notice Legal

Copyright© 2024 Fiserv. All rights reserved.

First Data Europe Limited, is a subsidiary of Fiserv, Inc. and is trading as Fiserv. First Data Europe Limited, is a private limited company incorporated in England (Company Number 02012925) with a registered address at Janus House, Endeavour Drive, Basildon, Essex, SS14 3WF. First Data Europe Limited is authorised and regulated by the UK Financial Conduct Authority (FCA Register No. 582703; CCA No. 739230). All trademarks, service marks, and trade names referenced in this material are the property of their respective owners.

v1.11

Want a quick overview?