Build Your Gateway
Step-by-step guide to create and complete a Gateway payment.
zahls.ch comes into play as soon as your buyer has submitted their data on your website and starts the payment.
Gateway Creation
Please read the API reference for all necessary information.
You will learn about API request basics at zahls.ch and can continue with creating a Gateway.
Payload
In addition to the required data, you are free to choose what you would like to transfer to zahls.ch.
Here are some parameters that might be interesting for you:
| Parameter | Data Type | Description |
|---|---|---|
| successRedirectUrl | string | After a successful payment, a redirection to this URL is made. Must be encoded. |
| failedRedirectUrl | string | After a failed payment, a redirection to this URL is made. Must be encoded. |
| cancelRedirectUrl | string | After a cancelled payment, a redirection to this URL is made. Must be encoded. |
| basket | array | A list of all product items. Used for email notifications and invoices |
| pm | string[] | Restrict the available payment methods with the according identifiers |
| preAuthorization | bool | Process a tokenization payment |
| reservation | bool | Process a pre-authorization payment |
| referenceId | string | This can be used to assign the zahls.ch transaction to an order later on |
| fields | array | Customer data goes here |
| skipResultPage | bool | Skip the zahls.ch result page Note: If a gateway is created with the skipResultPage flag and then used in an iframe integration, &appview=1 needs to be added to the gateway link |
| chargeOnAuthorization | bool | Tokenization - Execute an initial charge immediately |
| validity | int | For how long should your payment gateway be available |
| subscriptionState | bool | Set to true if you want to execute subscriptions |
| subscriptionInterval | string | Subscription - Payment interval (PHP interval specification) |
| subscriptionPeriod | string | Subscription - Duration (PHP interval specification) |
| subscriptionCancellationInterval | string | Subscription - How long a cancellation is possible (PHP interval specification) |
| lookAndFeelProfile | string | If you got multiple Look & Feel profiles, decide which one to use |
All Possible Fields
- title
- forename
- surname
- company
- street
- postcode
- place
- country
- delivery_title
- delivery_forename
- delivery_surname
- delivery_company
- delivery_street
- delivery_postcode
- delivery_place
- delivery_country
- phone
- date_of_birth
- terms
- privacy_policy
- custom_field_1
- custom_field_2
- custom_field_3
- custom_field_4
- custom_field_5
Examples
fields[forename][value]=John
fields[lastname][value]=Doe
fields[email][value]=john@doe.com
fields[street][value]=Burgstrasse 20
fields[postcode][value]=3600
fields[place][value]=Thun
fields[country][value]=CH
Languages
If multi-language support is enabled in the merchant backend, it is possible to provide multiple language translations in the API for Name and Description attributes.
Each language is identified by an ID:
| ID | Language |
|---|---|
| 1 | German |
| 2 | English |
| 3 | French |
| 4 | Italian |
| 7 | Dutch |
| 8 | Portuguese |
| 9 | Turkish |
| 10 | Polish |
| 11 | Spanish |
| 12 | Danish |
| 13 | Swedish |
| 14 | Norwegian |
Examples
# Without translation
fields[custom_field_1][name]=Fieldname
# With German and English translation
fields[custom_field_1][name][1]=Feldname
fields[custom_field_1][name][2]=Fieldname
Response
After the gateway was created successfully, you will get a link in the response of your request.
Redirect the shopper to this link for processing the payment.
Payment
Your shopper can choose a payment method in the Gateway and process the payment:
After Payment
The shopper is redirected to the matching URL depending on the outcome of the payment process. (success-/cancel-/failedRedirectUrl)
Next Steps
Now you have to perform further steps based on the payment result.