Local Payments
Introduction
The Local Payments solution offers a unique combination of global coverage, a single contracting and integration experience, and a broad and expanding portfolio of local payment methods.
Local Payments, also often referred to as Alternative Payment Methods, are defined as payment transactions where neither credit/debit cards or paper currencies are used as the form of payment. These payment methods are primarily used in eCommerce and mCommerce transactions, although some solutions are making a push for adoption at point-of-sale locations. In many markets, they are more commonly used than credit/debit cards.
Local Payments differ from card/association processing in a number of ways. They are generally designed to meet local needs and used in one or a limited number of markets. Unlike traditional credit/debit card processing, pricing across these payment methods is not uniform and retail pricing depend on local costs and merchant industries (e.g.: high-risk vs. low risk). Local Payments offerings and user experiences also vary greatly, though most are quite different from debit/credit user experiences.
Local Payments help you reach and securely process payments from a broader base of consumers in each local market, reduce shopping cart abandonment/improve conversion and improve customer experiences. They enable more consumers to shop online easily and confidently (i.e.: provide easy access to secure payment methods for those that are unbanked and/or without credit or debit cards), expand their ability to access international merchants and enable them to ’pay their way,’ all of which improve their shopping experiences and overall satisfaction.
Payment methods supported in a collecting model through the Fiserv Local Payments offering
| Payment Method Name | Payment Type | Customer’s Country / Region | Timeouts |
|---|---|---|---|
| Alipay | eWallet | China | 240 minutes (4hours) |
| Bancontact | Local Card Brand | Belgium | 60 minutes (1 hour) |
| eps | Bank Payment | Austria | 60 minutes (1 hour) |
| iDEAL | Bank Payment | Netherlands | 30 minutes |
| Multibanco | Bank Payment | Portugal | 10,080 minutes (7 days) |
| MyBank | Bank Payment | France, Italy | 30 minutes |
| paysafecard | Prepaid Voucher | Austria, Australia, Belgium, Bulgaria, Canada, Croatia, Cyprus, Czech Republic, Denmark, Finland, France, Georgia, Germany, Gibraltar, Greece, Hungary, Ireland, Italy, Liechtenstein, Lithuania, Luxembourg, Malta, Mexico, Netherlands, New Zealand, Norway, Peru, Poland, Portugal, Romania, Slovakia, Slovenia, Spain, Sweden, Switzerland, United Kingdom, Uruguay | 120 minutes (2 hours) |
| Przelewy24 | Bank Payment | Poland | 60 minutes (1 hour) |
| SEPA Direct Debit | Direct Debit | European Economic Area (E.E.A.) | Model A: 1 440 minutes (24 hours) Model C: N/A |
| SOFORT Banking / Klarna Pay Now | Bank Payment | Austria, Belgium, Germany, Netherlands, Spain | 60 minutes (1 hour) |
| Trustly | Bank Payment | Denmark, Estonia, Finland, Germany, Italy, Malta, Netherlands, Norway, Poland, Spain, Sweden, United Kingdom | 10,080 minutes (7 days) |
| SafetyPay | Cash & Bank Payments | Brazil, Mexico, Chile, Ecuador & Peru (more than 30 Local Payment Methods) | 1 800 minutes (30 hours) Customizable in the payment request |
Initiating a Sale transaction
A sale transaction for most Local Payments requires a direct interaction with the consumer who needs to be redirected to the payment method’s screens (e.g.: the login page of the consumer’s bank or a wallet provider) and back to your website after all required steps are completed.
As we handle all the required redirections to the various stakeholders for you, all you need to do is to post a form to a URL with the parameters and values required for the transaction.
URL for a test transactions: https://test.ipg-online.com/connect/gateway/processing
You will get the production URL with your production account credentials.
When building a request, independently of the payment method, there are some mandatory fields that need to be included in every request for a Sale transaction.
Example of a form with the minimum number of fields:
<form method="post" action="https://test.ipg-online.com/connect/gateway/processing">
<input type="hidden" name="txntype" value="sale">
<input type="hidden" name="timezone" value="America/New_York"/>
<input type="hidden" name="txndatetime" value="<% getDateTime() %>"/>
<input type="hidden" name="hash_algorithm" value="HMACSHA256"/>
<input type="hidden" name="hashExtended" value="<% call createExtendedHash ( "13.00","840" ) %>"/>
<input type="hidden" name="storename" value="541234567" />
<input type="hidden" name="checkoutoption" value="combinedpage"/>
<input type="text" name="chargetotal" value="13.00" />
<input type="hidden" name="currency" value="840"/>
<input type="submit" value="Submit">
</form>
Other generic fields to be considered
(M)=Mandatory (O)=Optional
| Field Name | Type | Description |
|---|---|---|
checkoutoption | M | Set the value for this parameter to "combinedpage" for a payment process where the payment method choice and the typical next step (e.g.: entry of card details or selection of bank) in consolidated in a single page. |
paymentMethod | O | You can submit the parameter ‘paymentMethod’ in your transaction request relevant for a selected local payment method as defined above. If you do not submit this parameter, the Gateway will display a page to your consumer to choose from the payment methods that are supported for the combination of the consumer’s country and the transaction currency. |
bname | M | The consumer’s name, e.g.: Albert Einstein. This is required for all Local Payments transactions. It is required for all Local Payments transactions, so we recommend including it in every Sale transaction request. If you do not submit this field, a hosted page will be displayed to the consumer to capture the name. |
bcountry | M | The consumer’s country in 2 Letter Country Code format, e.g.: US for the United States or DE for Germany. It is required for all Local Payments transactions, so we recommend to include it in every Sale transaction request. If you do not submit this field and the payment method requires it, a hosted page will be displayed with the country that we have identified based on IP address and the option to change the country, if not appropriate. |
Many of the payment methods are available for customers coming from a certain country. In the scenarios where you use the hosted payment page for payment selection, the Gateway can display to your consumers a hosted page with only these payment methods that are set up for your store and supported for the combination of the consumer’s country and the transaction currency. This validation is based either on the submitted billing country (bcountry) or the customer’s IP address.
See below an example of a hosted payment page in the checkout option combinedpage, where the country is pre-set to ‘Germany’ based on the customer’s IP address but still it can be changed via a dedicated drop-down, where else the payment methods are limited based on the combination country/currency.
When building a request for a specific payment method, except from the mandatory fields required for Sale transaction and some generic fields to be considered, you might also have to include some specific fields in your transaction request.
Payment method specific fields to be considered
(M)=Mandatory (O)=Optional (C)=Conditional
After your customer has decided how to pay, you present a corresponding HTML- page with a form to enter the payment data as well as hidden parameters with additional transaction information.
| Field Name | Relevant for | Description, possible values and format |
|---|---|---|
apmPaymentMethod | SafetyPay (O) | Enables the desired payment channel. Submit a value as: • ‘cash’ - for the cash payments • ‘online’ - for the online bank transfer payments If empty/null, all bank and cash payment methods will be made available |
timeout | SafetyPay (O) | You can submit a value for a transaction timeout in minutes to encourage your consumer to pay within a certain timeframe. |
customerid | Trustly (M) | Unique reference to identify the consumer (or transaction) for example from your CRM system. |
beneficiaryid | Trustly (C) | When asked for compliance purposes, submit ID, username, hash, or anything uniquely identifying the ultimate beneficiary. |
beneficiaryname | Trustly (C) | When asked for compliance purposes, submit the ultimate beneficiary’s full name. |
beneficiarycountrycode | Trustly (C) | When asked for compliance purposes, submit the ultimate beneficiary’s country of residence (two-letter ISO code). Example: ES |
beneficiaryaddress | Trustly (C) | When asked for compliance purposes, submit the ultimate beneficiary’s street address (street, zip code, city), excluding the country. Example: Main street 1, 12345, Barcelona |
termsaccepted | Przelewy24 (P24) (O) | Determines whether the GDPR page is displayed before the payment page. Submit a values as: • ‘0’ - the GDPR page is shown • ‘1’ - the GDPR page is not shown |
p24method | Przelewy24 (P24) (O) | The numeric identifier of a bank. Used for bypassing the P24 hosted payment page and redirecting to a pre-selected banking page. Submit a valid numeric value: Example: Sending ‘p24method’ set to ’25’ as part of your request redirects your consumer to the bank page. If an invalid value is sent for |p24method’ you consumer will be redirected to the P24 bank selection page. Due to the General Data Protection, P24 requires that the consumers accept their terms and conditions as an intermediate redirect before redirecting to the bank page. |
email | Przelewy24 (P24) (M) SEPA Direct Debit (M) | Consumer’s email address. For SEPA Direct Debit this parameter is mandatory only when you want to use the out-of-the-box solution offered by Fiserv. |
iban | SEPA Direct Debit (M) | Consumer’s IBAN - International Bank Account Number (up to 34 digits) |
mandateDate | SEPA Direct Debit (M) | To be populated with the initial mandate signature date. It is a mandatory to submit a mandateDate in case of recurring collections. |
mandateReference | SEPA Direct Debit (M) | To be populated with the mandate reference It is mandatory to submit a mandateReference in case of recurring collections. |
mandateType | SEPA Direct Debit (M) | Sequence type of Direct Debit, defaults to ‘single’. Values: • single - Direct Debit is executed once • firstCollection - First Direct Debit in a series of recurring • recurringCollection – Follow-up Direct Debit in a series of recurring • finalCollection – Last Direct Debit in a series of recurring |
mandateUrl | SEPA Direct Debit (M) | This parameter is mandatory only when you want to manage the SEPA Direct Debit mandates on your side. To be populated with the valid URL of the SEPA mandate to enable the Risk and Compliance department to access the details. |
bname | SEPA Direct Debit (M) | Name of the bank account owner that will be debited. |
baddr1 | SEPA Direct Debit (C) | Mandatory if IBAN belongs to EFTA and associated country. Street name and house number of the bank account owner that will be debited. |
bcity | SEPA Direct Debit (C) | Mandatory if IBAN belongs to EFTA and associated country. City of the bank account owner that will be debited. |
bcountry | SEPA Direct Debit (C) | Mandatory if IBAN belongs to EFTA and associated country. Country of the bank account owner that will be debited (2 letter country code). |
bzip | SEPA Direct Debit (C) | Mandatory if IBAN belongs to EFTA and associated country. Zip or postal code of the bank account owner that will be debited. |
mobileMode | Alipay (O) | You can submit this parameter with the value ‘true’ to enable Alipay for mobile web i.e.: the mobile enabled variant of Alipay. |
appToAppURL | Bancontact (O) | Custom app URL for redirecting the consumer back to the app, which triggered the payment. Alternatively, consider usage of the universal links. |
language | Bancontact (O) | The hosted payment page features 4 languages. Supported languages are: • ‘en_US’ - English • ‘nl_NL’ - Dutch • ‘de_DE’ - German • ‘fr_FR’ – French (default when no parameter specified) |
Valid numeric value
| Bank Name | Value |
|---|---|
| BLIK - PSP | 154 |
| Euro Bank | 94 |
| mBank - mTransfer | 25 |
| Place z IKO | 135 |
| Place z Orange | 146 |
| Przekaz tradycyjny | 178 |
| Raiffeisen Bank PBL | 102 |
| Użyj przedpłaty | 177 |
| Przekaz/Przelew tradycyjny | 1000 |
Initiating a Return transaction
When Return is supported for a selected local payment method, you can initiate a Return transaction with a reference to the Transaction ID of the original Sale transaction via API. Please check Post-authorisation & Returns API section for more information.
There is a limit for the amount of Return transactions to a maximum of 100 000 either EUR or USD, which are the only currencies that are applicable for this limit. Returns using other currencies will not be limited.
Transaction Response
Among all the details sent back to the defined response URLs as the transaction result, you might especially consider:
| Field Name | Description |
|---|---|
approval_code | Approval code for the transaction. The first character of this parameter is the most helpful indicator for verification of the transaction result: ‘Y’ indicates that the transaction has been successful ‘N’ indicates that the transaction has not been successful ?'” indicates that the transaction has been successfully initialized, but a final result is not yet available since the transaction is now in a waiting status. The transaction status will be updated at a later stage. |
status | Transaction status, e.g.: ‘APPROVED’, ‘DECLINED’ (by authorization endpoint or due to fraud prevention settings), ‘FAILED’ (wrong transaction message content/parameters, etc.) or ‘WAITING’ (asynchronous Alternative Payment Methods). |
fail_reason | Reason the transaction failed. Only if status = ‘DECLINED’ possible values are:• INPUT_DATA - There was a problem in the data passed/submitted • LOCAL_ERROR - Local system error • LOCAL_DECLINE - The transaction has been declined by the authorization endpoint • REMOTE_ERROR - There was a remote processing error • REMOTE_DECLINE - The transaction has been declined by a remote system (e.g.: payment process authentication failed) • TIMEOUT - There was a timeout while waiting for the transaction result • UNKNOWN - Transaction failed for unknown reasons (also default in reporting in case of succeeded transactions) • USER_ABORT - The user aborted the payment process |
Transaction Status
You need to be aware that, based on how many alternative payment methods work, there is always a chance for a transaction to get approved (succeed) after it has been initially marked as declined (failed) by the Gateway. The approved status on the other hand is final. This logic is applicable only for the Sale transactions, but not for the Returns transactions, which are immediately getting either approved or declined.
You will receive a notification in case approved-after-declined (succeed-after-failed) happens. The fail_reason will be overwritten once the succeeded notification has been sent.
SEPA Direct Debit
When you manage SEPA Direct Debit mandates on your side you can use these in combination with the "Local Payments" offering by submitting the reference and date of the mandate as well as a link to the mandate itself. This is useful in cases where you have a large number of mandates on file from previously used solutions and want to continue to collect the mandates and generate the pre-notification emails yourself.
Single payment or recurring payment
| Field Name | Mandatory / Optional / Conditional | Description |
|---|---|---|
email | Optional | Consumer’s email address to generate the pre-notification emails by yourself. |
iban | Mandatory | Consumer’s IBAN - International Bank Account Number (up to 34 digits). |
banme | Mandatory | Name of the bank account owner that will be debited. |
baddr1 | Conditional | Mandatory if IBAN belongs to EFTA and associated country. Street name and house number of the bank account owner that will be debited. |
bcity | Conditional | Mandatory if IBAN belongs to EFTA and associated country. City of the bank account owner that will be debited. |
bzip | Conditional | Mandatory if IBAN belongs to EFTA and associated country. Zip or postal code of the bank account owner that will be debited. |
mandateType | Optional | Sequence type of Direct Debit, defaults to ‘single’. • single - Direct Debit is executed once • firstCollection - First Direct Debit in a series of recurring • recurringCollection – Follow-up Direct Debit in a series of recurring • finalCollection – Last Direct Debit in a series of recurring |
mandateReference | Mandatory | Represents the mandate reference. |
mandateDate | Mandatory | Represents the initial mandate signature date. |
mandateUrl | Mandatory | Represents valid URL of the SEPA mandate to enable the Risk and Compliance department to access the details. |
When you do not want to manage the SEPA Direct Debit mandates on your side, you can instead use the out-of-box solution offered by Fiserv, where we collect the mandates and generate the pre-notification emails. Upon receiving the valid transaction request, the Gateway displays a hosted page to your customer with the mandate text and assigned mandate reference. It gives your consumer the option to consent or reject this mandate. As part of the Gateway’s response, you receive the mandate reference and mandate date, which have to be used in case of the subsequent payments under this mandate.
Single payment or first payment in recurring series
| Field Name | Mandatory / Optional / Conditional | Description |
|---|---|---|
email | Mandatory | Consumer’s email address to generate the pre-notification emails by the Gateway. |
iban | Mandatory | Consumer’s IBAN - International Bank Account Number (up to 34 digits). |
banme | Mandatory | Name of the bank account owner that will be debited. |
baddr1 | Conditional | Mandatory if IBAN belongs to EFTA and associated country. Street name and house number of the bank account owner that will be debited. |
bcity | Conditional | Mandatory if IBAN belongs to EFTA and associated country. City of the bank account owner that will be debited. |
bzip | Conditional | Mandatory if IBAN belongs to EFTA and associated country. Zip or postal code of the bank account owner that will be debited. |
mandateType | Optional | Sequence type of Direct Debit, defaults to ‘single’. Values: single - Direct Debit is executed once firstCollection - First Direct Debit in a series of recurring |
Subsequent payment in recurring series
| Field Name | Mandatory / Optional / Conditional | Description |
|---|---|---|
email | Mandatory | Consumer’s email address to generate the pre-notification emails by the Gateway. |
iban | Mandatory | Consumer’s IBAN - International Bank Account Number (up to 34 digits). |
banme | Mandatory | Name of the bank account owner that will be debited. |
baddr1 | Conditional | Mandatory if IBAN belongs to EFTA and associated country. Street name and house number of the bank account owner that will be debited. |
bcity | Conditional | Mandatory if IBAN belongs to EFTA and associated country. City of the bank account owner that will be debited. |
bzip | Conditional | Mandatory if IBAN belongs to EFTA and associated country. Zip or postal code of the bank account owner that will be debited. |
mandateType | Mandatory | Sequence type of Direct Debit. Values: recurringCollection – Follow-up Direct Debit in a series of recurring finalCollection – Last Direct Debit in a series of recurring |
mandateReference | Mandatory | Represents the mandate reference from the response. |
mandateDate | Mandatory | Represents the initial mandate signature date from the response. |
Transaction response includes additional SEPA Direct Debit specific fields:
| Field Name | Description |
|---|---|
mandateReference | Mandate reference as returned for the first direct debit transaction. |
mandateDate | Date of the initial direct debit transaction as returned for the first transaction. |
plannedDueDate | When you manage SEPA Direct Debit mandates on your side, you receive a UTC date (YYYY-MM-DD) with the planned due date (the earliest day that the funds will be debited from the consumer’s account). |
Updated 5 months ago
