Page tree
Skip to end of metadata
Go to start of metadata

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

ParameterRequiredShort Explanation

clearingtype

+

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:
register_alias

successurl+

URL for "payment successful"

Format

CHAR(2..255)

Scheme

<scheme>://<host>/<path>
<scheme>://<host>/<path>?<query>

scheme-pattern: [a-zA-Z]{1}[a-zA-Z0-9]{1,9}

backurl+

URL for "Back" or "Cancel"

Format

CHAR(2..255)

Scheme

<scheme>://<host>/<path>
<scheme>://<host>/<path>?<query>

scheme-pattern: [a-zA-Z]{1}[a-zA-Z0-9]{1,9}

errorurl+

URL for "faulty payment"

Format

CHAR(2..255)

Scheme

<scheme>://<host>/<path>
<scheme>://<host>/<path>?<query>

scheme-pattern: [a-zA-Z]{1}[a-zA-Z0-9]{1,9}

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

ParameterRequiredShort 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

CHAR(2..2000)

workorderid +

Reference ID to the generic Request. Has to be passed on to the following requests

The workorderid is a technical id returned from the PAYONE platform to identify a workorder. A workorder is a part of a payment process (identified by a txid). The workorderid is used for the genericpayment request.

Format

CHAR(1..50)

Example Response:

status=REDIRECT 
redirecturl=http://www.aliasregistrationpage.com 
workorderid=WORKORDERID12345

Genericpayment – get_alias

Request

ParameterRequiredShort 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

The workorderid is a technical id returned from the PAYONE platform to identify a workorder. A workorder is a part of a payment process (identified by a txid). The workorderid is used for the genericpayment request.

Format

CHAR(1..50)

add_paydata[action]+

For “get_alias” requests this has to be:
get_alias

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

ParameterRequiredShort Explanation
status+OK / ERROR 
workorderid +

Reference ID to the generic Request. 

The workorderid is a technical id returned from the PAYONE platform to identify a workorder. A workorder is a part of a payment process (identified by a txid). The workorderid is used for the genericpayment request.

Format

CHAR(1..50)

add_paydata[alias]-alias of the buyer 

Example Response:

status=OK 
add_paydata[alias]=yourcustomeralias 
workorderid=WORKORDERID12345 

Authorization

Request

ParameterRequiredShort 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.
(Permitted symbols: 0-9, a-z, A-Z, .,-,_,/)

Merchant reference number for the payment process (case insensitive)

Format

CHAR(1..20)
Permitted Symbols
[0-9][a-z][A-Z], .,-,_,/

narrative_text-

Dynamic text element on account statements
(3 lines with 27 characters each) and credit card statements.
Default-Value for narrative_text can be changed in PMI.

Dynamic text element on account statements

Format

CHAR(1..81)

(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

  • "company"
  • or "lastname"
  • or "firstname" plus "lastname"

Format

CHAR(2..50)

country+

Country (ISO 3166)

Specifies country of address for the customer

Format

LIST 

Permitted values

ISO 3166 2-letter-codes

Samples

DE
GB
US

Some countries require additional information in parameter "state"

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

ParameterRequiredShort Explanation
status +APPROVED / ERROR 
txid+

Payment process ID (PAYONE)
Mandatory on succes

The txid specifies the payment process within the PAYONE platform

Format

NUMERIC(9..12)

Example Response:

status=APPROVED 
txid=12345678 
userid=789654

Sequence Diagram of a Sale including Alias Registration

  • No labels