- Created by PAYONE Admin, last modified on 2022-08-12
Process of Alias Registration
To register a Postfinance alias, there are 3 steps to take:
Initiate Alias Registration
To start the alias registration you need to send a generic payment request with action “register_alias” to our server api.
Request Alias
The customer will be redirected to the postfinance alias registration page. After authorization, the customer will be redirected to your shop. When the customer has arrived, you can call the generic payment request with action “get_alias” to receive the registered alias. Save the alias in the customer’s profile, to use it for future authorizations. You will always use the same registered alias for this customer for every future authorization.
Request Payment with Alias
When the registration is finished, you can send an authorization request to our server api and send the alias in the request. When we receive an alias in the authorization, we will process an alias payment to postfinance. When you don’t send the alias, we will try to process a “normal” authorization to postfinance including a redirect of the customer.
Additional parameters for use with "genericpayment”
Standard parameters, such as aid or key aren’t listed in the following table, but shown in the example request. Please read the Server Api documentation for full parameter list.
Genericpayment – register_alias
Request
| Parameter | Required | Short Explanation |
|---|---|---|
| + | Needs to be "sb" | |
| onlinebanktransfertype | + | Needs to be "PFC" |
| bankcountry | + | Needs to be ‘CH’ |
| currency | + | Needs to be ‘CHF’ |
| country | + | Needs to be ‘CH’ |
| add_paydata[action] | + | For “register_alias” Requests this has to be: |
| successurl | + | URL for "payment successful" Format Scheme |
| backurl | + | URL for "Back" or "Cancel" Format Scheme |
| errorurl | + | URL for "faulty payment" Format Scheme |
Example Request:
add_paydata[action]=register_alias aid=12345 (your aid) mid=23456 (your mid) portalid=12345123 (your portalid) key=abcdefghijklmn123456789 (your key) api_version=3.10 clearingtype=sb currency=CHF country=CH bankcountry=CH encoding=UTF-8 mode=test (set to „live“ for live-requests) request=genericpayment onlinebanktransfertype=PFC
Response
| Parameter | Required | Short Explanation |
|---|---|---|
| status | + | REDIRECT / ERROR |
| redirecturl | + | URL to redirect the customer. The customer needs to authenticate the alias_registration at postfinance. Redirect URL → zMerchant system has to redirect customer to this URL to complete payment Format |
| workorderid | + | Reference ID to the generic Request. Has to be passed on to the following requests Format |
Example Response:
status=REDIRECT redirecturl=http://www.aliasregistrationpage.com workorderid=WORKORDERID12345
Genericpayment – get_alias
Request
| Parameter | Required | Short Explanation |
|---|---|---|
| clearingtype | + | Needs to be "sb" |
| onlinebanktransfertype | + | Needs to be "PFC" |
| country | + | Needs to be ‘CH’ |
| bankcountry | + | Needs to be ‘CH’ |
| currency | + | Needs to be ‘CHF’ |
| workorderid | + | Reference ID to the generic request register_alias Format |
| add_paydata[action] | + | For “get_alias” requests this has to be: |
Example Request:
add_paydata[action]=get_alias aid=12345 (your aid) mid=23456 (your mid) portalid=12345123 (your portalid) key=abcdefghijklmn123456789 (your key) api_version=3.10 clearingtype=sb bankcountry=CH currency=EUR encoding=UTF-8 mode=test request=genericpayment onlinebanktransfertype=PFC workorderid=WORKORDERID12345
Response
| Parameter | Required | Short Explanation |
|---|---|---|
| status | + | OK / ERROR |
| workorderid | + | Reference ID to the generic Request. Format |
| add_paydata[alias] | - | alias of the buyer |
Example Response:
status=OK add_paydata[alias]=yourcustomeralias workorderid=WORKORDERID12345
Authorization
Request
| Parameter | Required | Short Explanation |
|---|---|---|
| clearingtype | + | Needs to be "sb" |
| onlinebanktransfertype | + | Needs to be "PFC" |
| amount | + | Total amount (in smallest currency unit! e.g. cent) Specifies the total gross amount of a payment transaction. Value is given in smallest currency unit, e.g. Cent of Euro; Pence of Pound sterling; Öre of Swedish krona. The amount must be less than or equal to the amount of the corresponding booking. Format NUMERIC(1..10) Permitted values max. +/- 19 999 999 99 |
| add_paydata[alias] | + | Alias for postfinance alias payment |
| currency | + | Currency (ISO 4217) Specifies currency for this transaction Format LIST Permitted values ISO 4217 (currencies) 3-letter-codes Samples EUR USD GBP |
| reference | + | Merchant reference number for the payment process. Format |
| narrative_text | - | Dynamic text element on account statements Dynamic text element on account statements Format (3 lines with 27 characters each) and credit card statements. |
| lastname | + | Surname Last name of customer; optional if company is used, i.e.: you may use
Format CHAR(2..50) |
| country | + | |
| bankcountry | + | Needs to be ‘CH’ |
Example Request:
aid=12345 (your aid) mid=23456 (your mid) portalid=12345123 (your portalid) key=abcdefghijklmn123456789 (your key) clearingtype=sb amount=6413 api_version=3.10 onlinebanktransfertype=PFC currency=CHF encoding=UTF-8 lastname=Master reference=youranyreference mode=test request=authorization country=CH bankcountry=CH add_paydata[alias]=youralias123456
Response
| Parameter | Required | Short Explanation |
|---|---|---|
| status | + | APPROVED / ERROR |
| txid | + | Payment process ID (PAYONE) Format |
Example Response:
status=APPROVED txid=12345678 userid=789654
Sequence Diagram of a Sale including Alias Registration
Special Case: WebView Handling in Android
If you want to show PostFinance as a payment method in your Android app, it's important to make sure to correctly configure the webview client to launch the PostFinance app when redirected to a Postfinance universal link.
Here's a code example shared by Postfinance:
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()
}
}
- No labels