PostFinance Card & eFinance

Via the Saferpay JSON API, payments can be handled through PostFinance Card and eFinance.

Requirements

Acceptance of PostFinance Card & eFinance requires:

• A corresponding license and thus a valid identification with a username and password for the Saferpay system.

• A valid contract with PostFinance.

Supported features

Feature	Support
Capture/Cancel	✅
Multipart Captures	❌
Secure Card Data	✅ Needs attention!
Refunds	✅ Needs attention!
Recurring Payments	✅ Needs attention!
3D Secure	❌
Dynamic Currency Conversion (DCC)	❌
Mail Phone Order	❌
Testing	✅
Omni-Channel	❌

Integration

The general integration of PostFinance eFinance/Card can be done via the Payment Page -However, other features require a different path. See further down in this chapter- and requires the following things to be noted:

PostFinance transactions are only valid for 30 days and must be captured in this time frame. After 30 days, the reservation will void and the authorized amount can no longer be transferred! However you have a guaranteed payout, within these 30 days!

Refunds may only be executed up to 14 months, after the original transaction.

Storage in the Secure Card Data Store

If you intend on saving PostFinance Card-data for later use, Saferpay provides the possibility of storing PostFinance’s Postcard inside the Saferpay Secure Card store. For this, the following requirements must be met:

• Activation of Saferpay Secure Card Data in the Saferpay merchant account.

• The feature must also be activated on PostFinance side.

• Only the PostFinance Card is supported, not eFinance!

Alias Insert Request

The registration is done via the Saferpay Alias Store. Within the Alias Insert Request, you need to specify the parameter Type with the value POSTFINANCE, which signals, that you want to save Postcard payment means.

Request

{
  "RegisterAlias": {
    "IdGenerator": "RANDOM_UNIQUE"
  },
  "Type": "POSTFINANCE",
  "LanguageCode": "en",
  "RequestHeader": {
    "SpecVersion": "1.14",
    "CustomerId": "242225",
    "RequestId": "5f543be575b3f3ecff3214257ac6978a",
    "RetryIndicator": 0,
    "ClientInfo": {
      "ShopInfo": "My Shop",
      "OsInfo": "Windows Server 2013"
    }
  },
  "ReturnUrls": {
    "Success": "https://www.myshop.com/success",
    "Fail": "https://www.myshop.com/fail",
    "Abort": "https://www.myshop.com/abort"
  }
}

Response

{
  "ResponseHeader": {
    "SpecVersion": "1.14",
    "RequestId": "5f543be575b3f3ecff3214257ac6978a"
  },
  "Token": "y6678qfw3dm9pule1inqkpr1o",
  "Expiration": "2019-11-15T14:39:16.642+01:00",
  "RedirectUrl": "https://test.saferpay.com/vt2/api/register/twint/242225/y6678qfw3dm9pule1inqkpr1o"
}

Redirect to PostFinance

The RedirectUrl then needs to be opened inside an iFrame, as a redirect, or lightbox.

Unlike with credit cards, PostFinance requires the card holder to agree to registration on its site, so a redirect will be done!

1 - Confirmation dialogue on PostFinance:

(click to enlarge)

2 - After clicking on Next, card holders are asked to enter their card ID:

(click to enlarge)

3 - Card holders must then confirm registration by entering a TAN. This is created using a card reader:

(click to enlarge)

4 - After registration, the result is displayed to the customer, who is then returned to the shop:

(click to enlarge)

Redirect to Shop

Once this process is done, the user gets redirected towards one of the previously defined ReturnUrls, depending on the outcome.

Alias Assert Insert

The merchant system then needs to execute the Alias Assert Insert Request, in order to gather the alias and other important payment mean details.

Request

{
  "Token": "67tdpr8keb3ky3y6728kqv4gk",
  "RequestHeader": {
    "SpecVersion": "1.14",
    "CustomerId": "242225",
    "RequestId": "22c449e9cb06a227491c0f18532d9ef1",
    "RetryIndicator": 0,
    "ClientInfo": {
      "ShopInfo": "My Shop",
      "OsInfo": "Windows Server 2013"
    }
  }
}

Response

{
  "ResponseHeader": {
    "SpecVersion": "1.14",
    "RequestId": "22c449e9cb06a227491c0f18532d9ef1"
  },
  "Alias": {
    "Id": "a2f4d6390bdf5ba4ed9d0c0f2318bc2b",
    "Lifetime": 1000
  },
  "PaymentMeans": {
    "Brand": {
      "PaymentMethod": "POSTCARD",
      "Name": "Postcard"
    },
    "DisplayText": "xxxxxxxx123",
    "Card": {
      "MaskedNumber": "xxxxxxxx123",
      "ExpYear": 2021,
      "ExpMonth": 7
    }
  }
}

Using the Alias

Once you have obtained the alias, you can go ahead and execute your recurring/subsequent transaction using the Transaction AuthorizeDirect request. The alias is set within the PaymentMeans.Alias container, but remember, that this transaction, like all PostFinance transactions, also must be captured for the money to flow.

Web View Web-to-App switch

If you are integrating PostFinance inisde a web-view, you may have to specifically configure your view, in order for the PostFinance app to open.

Here is example-code on how this is achieved.

This code has been directly provided by PostFinance. If you have any questions, please ask PostFinance for help.

Android

private fun setUpWebViewClient() {
        binding.webView.webViewClient = object : WebViewClient() {
            override fun shouldOverrideUrlLoading(view: WebView?, url: String?): Boolean {
                Log.d(this@WebViewActivity::class.java.simpleName, "shouldOverrideUrlLoading: $url")
                if(url?.contains("universal.postfinance.ch/") == true) {
                    startActivity(Intent(Intent.ACTION_VIEW, Uri.parse(url)))
                    return true
                }
                return false
            }
 
            override fun onPageFinished(view: WebView?, url: String?) = onLoadingFinished()
 
            override fun onReceivedError(
                view: WebView?,
                request: WebResourceRequest?,
                error: WebResourceError?
            ) = onLoadingFinished()
        }
    }

Testing

Please refer to this chapter, if you want to test PostFinance.