Swissbilling
1. Introduction
SwissBilling is a Swiss company (part of Cembra Money Bank) that was created in 2011. It focuses on delivering an easy to use online payment method that offers payment via invoice for Swiss online customers. This solution allows the customer to pay for a purchase in x days after receiving it. The merchant can modify the invoice before (cancellation) or after (refund) the shipment.
Before accepting a payment, Swissbilling uses creditworthiness checks based on validations against Swiss databases and SwissBilling customers' credit history. When approving an order, SwissBilling opens a credit note for these customers and decides on their eligibility and payment requests.
Pay by Invoice is the most preferred payment method by Swiss consumers.
2. Flow
A transaction via SwissBilling will have the following flow:- The consumer fills his/her shopping basket on the merchant website, checks out, and selects SwissBilling as the payment method. This payment method selection page can be hosted by the merchant or by PostFinance.
- The consumer is redirected to SwissBilling, via an URL provided by SwissBilling, which includes a unique transaction reference and merchant identification.
- The consumer applies to pay via Pay by Invoice (payment after delivery). SwissBilling then checks the consumer’s creditworthiness.
- The consumer is redirected back to the merchant via PostFinance. The merchant then receives a transaction status simultaneously through PostFinance.
3. Integration
3.1 Configuration
To activate the payment method, the merchant will need to have an acquiring contract with SwissBilling.
Creating new SwissBilling transaction works in e-Commerce mode only. Please make sure to send requests (in POST mode) always to our UTF-8 URL version.
Once a sales agreement with a payment method is signed, the merchant needs to contact our Merchanthelp to configure and activate the payment method.
After the configuration and activation, it can be found in the Web-banking section of the "Payment methods" in your PostFinance account.
- The procedure to set up an account is as follows:
- The merchant signs a contract with SwissBilling.
- The merchant or SwissBilling provides details to Merchanthelp.
- PostFinance will take care of the SwissBilling activation for the merchant.
3.2 Payment method selection
| Description |
|---|
| PM / BRAND: SwissBilling |
3.3 Input parameters
| Parameter | Description |
|---|---|
| PSPID |
Your affiliation name in our system |
| ORDERID | Merchant Order reference Length: 50 Mandatory |
| Customer's email address Length: 6 Mandatory |
|
| AMOUNT | Transaction amount Length: 6 Mandatory |
| CURRENCY | Currency of the order (alway CHF with SwissBilling) Length: ISO Alpha code Mandatory |
| LANGUAGE | Language of the customer Length: 5 Optional |
| REF_CUSTOMERID | Customer number Length: 20 Optional |
| ECOM_BILLTO_COMPANY | Customer company name Length: 50 Optional |
| ECOM_BILLTO_POSTAL_NAME_PREFIX | Customer's prefix Length: 4 Optional |
| ECOM_BILLTO_POSTAL_NAME_LAST | Customer's last name Length: 35 Mandatory |
| ECOM_BILLTO_POSTAL_NAME_FIRST | Customer's first name Length: 35 Mandatory |
| ECOM_BILLTO_POSTAL_STREET_NUMBER | Customer's street number Length: 10 Mandatory |
| ECOM_BILLTO_POSTAL_STREET_LINE1 | Customer's street (line 1) Length: 35 Mandatory |
| ECOM_BILLTO_POSTAL_STREET_LINE2 | Customer's street (line 2) Length: 35 Optional |
| ECOM_BILLTO_POSTAL_POSTALCODE | Customer's postal code Length: 5 Mandatory |
| ECOM_BILLTO_POSTAL_CITY | Customer's city Length: 25 Mandatory |
| ECOM_BILLTO_POSTAL_COUNTRYCODE | Customer's country code Length: 2 Mandatory |
| ECOM_BILLTO_TELECOM_MOBILE_NUMBER | Customer's mobile number Length: 20 Optional |
| ECOM_BILLTO_TELECOM_PHONE_NUMBER | Customer's phone number Length: 20 Optional |
| ECOM_SHIPTO_COMPANY | Customer delivery company name Length: 50 Optional |
| ECOM_SHIPTO_POSTAL_NAME_PREFIX | Customer's delivery prefix Length: 4 Optional |
| ECOM_SHIPTO_POSTAL_NAME_FIRST | Customer's delivery first Name Length: 35 Mandatory |
| ECOM_SHIPTO_POSTAL_NAME_LAST | Customer's delivery last Name Length: 35 Mandatory |
| ECOM_SHIPTO_POSTAL_STREET_NUMBER | Customer's delivery street number Length: 10 Mandatory |
| ECOM_SHIPTO_POSTAL_STREET_LINE1 | Customer's delivery street (line 1) Length: 35 Mandatory |
| ECOM_SHIPTO_POSTAL_STREET_LINE2 | Customer's delivery street (line 2) Length: 35 Optional |
| ECOM_SHIPTO_POSTAL_POSTALCODE | Customer's delivery postal code Length: 5 Mandatory |
| ECOM_SHIPTO_POSTAL_CITY | Customer's delivery city Length: 25 Mandatory |
| ECOM_SHIPTO_POSTAL_COUNTRYCODE | Customer's delivery country code Length: 2 Mandatory |
| ECOM_SHIPTO_TELECOM_MOBILE_NUMBER | Customer's delivery mobile number Length: 20 Optional |
| ECOM_SHIPTO_TELECOM_PHONE_NUMBER | Customer's delivery phone number Length: 20 Optional |
| GENERIC_BL_DATA | Merchant generic blacklist info Length: 50 Optional |
| ITEMIDX | Item identifier Length: 15 Mandatory |
| ITEMNAMEX | Item name Length: 40 Mandatory |
| ITEMPRICEX | Item unit price. ITEMPRICEX only accepts the input amount Length: 10 Mandatory |
| ITEMVATCODEX | ITEM VAT code Length: 6 Mandatory |
| ITEMQUANTX | Item quantity Length: 4 Mandatory |
| ITEMCATEGORYX |
Item category ITEMCATEGORYX only accepts the following values:
You have to use 1* ITEMCATEGORY per item, for example: <input type="hidden" name="ITEMCATEGORY1" value="SPORT"/> <input type="hidden" name="ITEMID1" value="2855"/> <input type="hidden" name="ITEMNAME1" value="Adibok Supershoe"/> <input type="hidden" name="ITEMPRICE1" value="3999"/> <input type="hidden" name="ITEMQUANT1" value="1"/> <input type="hidden" name="ITEMVATCODE1" value="20%"/> <input type="hidden" name="TAXINCLUDED1" value="1"/> |
| TAXINCLUDEDX | Always must be sent with TAXINCLUDEDX=1 (ITEMPRICEX is including VAT) Length: 1 Mandatory |
IMPORTANT REMARKS
- SwissBilling can only be used with CHF and Swiss customers. An item price must also be higher than 0.00CHF.
- The merchant can choose B2B or B2C solution at enrollment; for B2B, the company name parameters are mandatory.
- Shipping and Billing addresses must be identical for SwissBilling to approve the order!
4. Transaction processing and maintenance operations
4.1 Performing maintenance operations
Maintenance operations (such as: data captures, cancellations, refunds, etc.) for SwissBilling can be operated via the standard manual functionalities offered in the Back Office or via DirectLink (Direct Maintenance).
4.1.1 Performing maintenance operations through the Back Office
Confirm authorised transactions
Go through the following steps if you want to process and confirm your transactions with the payment procedure "Data capture by the trader (manual or automatic)":
1. Select this option at "Configuration > Technical information > Global transaction parameters > Default data capture (payment) procedure".
2. Confirm the transaction manually when the status is “5 - Authorised”. An authorisation is only a reservation of the amount on your customer’s card/account (or a match against a blacklist). It does NOT implicate a payment.
a. Look up the transaction via "Operations > View transactions".
b. Click the "Confirm Payment (data capture): XXXXXXXX/X" button at the bottom of the order details tab.
- The status changes to “91 - Payment processing".
- Once we have received the confirmation of data capture from your acquirer, the status changes to “9 - Payment requested". This status means we have requested your acquirer to transfer the money that had been reserved to your bank account. As it is your acquirer that transfers the amount to your bank account, we are unable to say exactly when you will receive the payment.
Do you prefer automated operations?
Batch: Send the operation code SAS in field 10
DirectLink: Send operation=SAS
Delete and refund payments
Delete a payment
A payment deletion is the action of cancelling a payment request made to an acquirer. This is only possible for credit card payments. The deletion of a payment implies that the money normally is not withdrawn from the customer's bank account (neither debit nor credit performed on the customer's bank account).
Constraint: a payment may be deleted on the day of the data capture up until the cut-over time (as configured for your account). The cut-over time is when we send all payment requests to the acquirer. The cut-over time can vary depending on the acquirer, but is usually 16:00h or 24:00h CET. If the customer changes his mind after this deadline has expired, you will need to reimburse the money.
To delete a payment:
1. Look up the transaction via "Operations > View transactions".
2. Click the "Delete payment: XXXXXXXX/X" button at the bottom of the "Orders" tab.
Do you prefer automated operations?
Batch: Send the operation code DES in field 10
DirectLink: Send OPERATION=DES
Refund a payment
A refund implies that the money had initially been debited and was later credited back to the cardholder’s bank account. Both movements will appear on the cardholder’s statement.
Constraints:
- The option needs to be activated for your account.
- Your acquirer must allow refunds.
- Refunds must be possible for the specific payment method. The availability of the refund option depends on your subscription.
If your acquirer doesn't allow automated refunds, refunds must be performed directly by your acquirer.
How to refund a payment?
1. Look up the transaction you want to refund via the "View transactions > Transaction details".
2. Click on the “Refund” button which is displayed at the bottom of the "Orders" tab. You can also log a reason for the refund.
Do you prefer automated operations?
Batch: Send the RFS operation code in field 10
DirectLink: Send OPERATION = RFS
Do you want to refund more than the paid amount?
For credit cards it's possible to make a refund for a higher amount than the originally paid amount. However, you need to bear the aforementioned constraints in mind, together with the possibility whether your credit card acquirer supports this "exceeding refund" possibility. Also, the Partial maintenance option needs to be activated on your account, so that you can change the original amount in the transaction overview. If you wish to make use of this functionality, you need to contact our MerchantHelp team.
Do you want to refund more than the paid amount?
For credit cards it's possible to make a refund for a higher amount than the originally paid amount. However, you need to bear the aforementioned constraints in mind, together with the possibility whether your credit card acquirer supports this "exceeding refund" possibility. Also, the Partial maintenance option needs to be activated on your account, so that you can change the original amount in the transaction overview. If you wish to make use of this functionality, you need to contact our MerchantHelp team.
Special operations on authorised transactions
Requesting an authorisation implies checking the validity of a card/account and the amount of money available on it. Each acquirer can then reserve the specific amount of money requested on the customer's card/account for a predefined period of time and for a specific merchant. Besides requesting an authorisation, our system also allows you to delete and renew authorisations and perform manual authorisations. The latter two operations are only possible for credit card payments.
Delete an authorisation
Whenever a transaction is authorised, it means the acquirer is reserving a specific sum on the customer’s card/account (or the request is matched against a blacklist), to be paid to you when the payment is requested. Although our platform allows you to delete an authorisation, not all acquirers support this type of
operation.
To delete an authorisation via our platform, look up the transaction via the “View transactions” selection screen and click on the “Cancel authorisation” button at the bottom of the order details page. We will simulate the authorisation deletion in any case, even if the acquirer doesn’t support this operation.
Do you prefer automated operations?
Batch: Send the operation code DES in field 10
DirectLink: Send OPERATION=DES
Renew an authorisation
An authorisation’s validity period depends on the acquirer. In transaction details, you will see the days remaining before the authorisation for each transaction expires. This number of days is given as an indication only. The exact authorisation period is specified in the contract with your acquirer.
If the authorisation has not been followed by a data capture (payment request) within the predefined timeframe, the authorisation will be displayed in red, meaning it has expired. The merchant's guarantee that the money is still available for him on the customer’s card/account no longer exists.
You could request the payment anyway (without a valid authorisation), but the payment may be refused (e.g. in the event of insufficient funds). Before requesting the payment, you could renew the authorisation in your back office. This means you are requesting the acquirer to reserve the money for you once again. However, it is possible that the cardholder has used his card in the meantime and that there are no longer sufficient funds for you to be paid.
To renew an authorisation, look up the transaction via the “View transactions” selection screen and click on the "Redo authorisation" button at the bottom of the order details page (if the button is not immediately available, click on the "Advanced" button first). If the original authorisation was obtained with the 3-D Secure protocol, the original 3-D Secure conditions may no longer apply to the renewed authorisation.
In accordance with the VISA International and MasterCard International Regulations, the customer has to identify himself for each authorisation in order to benefit from the 3-D Secure guarantee. The 3-D Secure conditional payment guarantee rules are exclusively managed between the merchant (you) and his acquirer. Please contact your acquirer for more information.
The availability of the “Redo authorisation” option depends on your subscription. The option needs to be activated by our Merchanthelp.
Do you prefer automated operations?
Batch: Send the operation code REN in field 10
DirectLink: Send operation=REN
Perform a manual authorisation
Sometimes the acquirer does not issue the authorisation automatically, e.g. when you have reached your permitted transaction limit. The acquirer will refuse the authorisation and return a message asking you to contact its merchant call centre. When you contact the acquirer and he decides to issue the authorisation, he may give you an authorisation code over the phone. You can enter the authorisation code the acquirer has given you (over the phone or via fax, etc.) in your back office. Look up the transaction via the “View transactions” selection screen. When you invoke the transaction details, you will see a “Manual Authorisation” button at the bottom of the page (if the button is not immediately available, click on the "Advanced" button first). Enter the authorisation code the acquirer has given you in the field next to the “Manual Authorisation” button and click the “Manual Authorisation” button.
As the merchant, you are fully responsible for the manual entry of the authorisation code, even if the transaction is in status 9 afterwards and no actual payment is performed. If you have a 3-D Secure contract with your acquirer, the 3-D Secure conditions which apply for a standard authorisation issued via the 3-D Secure protocol, may differ from those for a manual authorisation. In accordance with the VISA International and MasterCard International Regulations, the customer has to
identify himself for each authorisation in order to benefit from the 3-D Secure guarantee. The 3-D Secure
conditional payment guarantee rules are exclusively managed between the merchant (you) and his acquirer.
Please contact your acquirer for more information.
Partial and Multiple operations
Partial operations allow you to perform data captures, authorisation cancellations and refunds for a smaller amount than the original order. Multiple operations allow you to perform several data captures, authorisation cancellations and refunds on the same transaction (the multiple operations option is a separate option from
the partial operations option). The availability of the partial and multiple operations options depends on your subscription and whether your acquirer allows these operations. The options need to be activated by our Merchanthelp. When the partial operations option is enabled in your account, next to the maintenance
buttons at the bottom of the order details page, you will see entry fields where you can enter an amount. When the multiple operations option is enabled in your account, you will see a “Last one” check box next to the text fields where you can enter an amount.
Partial operations
To perform a partial data capture/refund/authorisation/deletion, you have to go to the detailed transaction page, where you will find the "Confirm Payment (data capture)"/refund/"Delete authorisation" button at the bottom of the page.
1. Fill in the partial amount in the field next to the respective button (by default, the full amount will be entered).
2.Click the respective button and confirm.
Do you prefer automated operations?
Data captures
Batch: Send the operation code SAS in field 10
DirectLink: Send OPERATION=SAS
Refunds
Batch: Send the operation code RFS in field 10
DirectLink: Send OPERATION=RFS
Authorisation deletion
Batch: Send the operation code DES in field 10
DirectLink: Send OPERATION=DES
Multiple operations
To perform multiple data captures/refunds or an authorisation deletion leaving the transaction open for further maintenance operations, you have to go to the detailed transaction page where you will find the "Confirm payment (data capture)"/refund/"Delete authorisation" button at the bottom of the page.
1. Fill in the partial amount in the field next to the respective button (by default, the full amount will be entered).
2. Tick the “Last one” tick box if this is the last operation you want to perform on this transaction OR disable the “Last one” tick box if you still wish to perform a subsequent operation on this transaction (e.g. request 50.00 EUR for the goods you already dispatched the customer and request the remaining transaction amount when you dispatch the rest).
3. Click the respective button and confirm.
Do you prefer automated operations?
Data captures
Batch: Send the operation code SAL (not last) or SAS (last) in field 10
DirectLink: Send OPERATION=SAL (not last) or OPERATION=SAS (last)
Refunds
Batch: Send the operation code RFD (not last) or RFS (last) in field 10
DirectLink: Send OPERATION=RFD (not last) or OPERATION=RFS (last)
Authorisation deletion
Batch: Send the operation code DEL (not last) or DES (last) in field 10
DirectLink: Send OPERATION=DEL (not last) or OPERATION=DES (last)
4.1.2 Performing maintenance operations through DirectLink
Direct MaintenanceA direct maintenance request from your application allows you to:
- Perform a data capture (payment) of an authorised order automatically (as opposed to manually in the back office);
- Cancel an authorisation of an order;
- Renew an authorisation of an order;
- Refund a paid order.
Data captures, authorisation cancellations and authorisation renewals are specifically for merchants who have configured their account/requests to perform the authorisation and the data capture in two steps.
Maintenance request
1. Request URL
The request URL in the TEST environment is https://e-payment.postfinance.ch/ncol/test/maintenancedirect.asp.
The request URL in the PRODUCTION environment is https://e-payment.postfinance.ch/ncol/prod/maintenancedirect.asp.
Change "test" to "prod"
Replace “test” with “prod” in the request URL when you switch to your production account. If you forget to change the request URL, once you start working with real orders, your maintenance transactions will be sent to the test environment and will not be sent to the acquirers/banks.
1.2 Request parameters
The following table contains the mandatory request parameters for performing a maintenance operation:
| Field | Description |
|---|---|
| AMOUNT | Order amount multiplied by 100. This is only required when the amount of the maintenance differs from the amount of the original authorisation. However, we recommend its use in all cases. Our system will check that the maintenance transaction amount is not higher than the authorisation/payment amount. |
| OPERATION |
Possible values:
|
| ORDERID | You can send the PAYID or the orderID to identify the original order. We recommend the use of the PAYID. |
| PAYID | Your account's PSPID |
| PSPID | The ID of your PSP |
| PSWD | Password of your API-user |
| SHASIGN |
Signature (hashed string) to authenticate the data (see SHA-IN-signature) |
| USERID |
Your API user |
1.2.1 Test page
You can test direct maintenance requests here: https://e-payment.postfinance.ch/ncol/test/testdm.aspData captures, authorisation cancellations and authorisation renewals are specifically for merchants who have configured their account/requests to perform the authorisation and the data capture in two steps.
2. Maintenance response
Our server returns an XML response to the maintenance request:
Example of an XML response to a direct maintenance request
<?xml version=”1.0”?>
< ncresponse orderID=”99999” PAYID=”1111111” PAYIDSUB=”3” NCSTATUS=”0” NCERROR=””
NCERRORPLUS=”” ACCEPTANCE=”12345” STATUS="91" amount="125" currency="EUR"/>
The following table contains a list of the ncresponse tag attributes:
| Field | Description |
|---|---|
| ACCEPTANCE | Acceptance code returned by acquirer |
| AMOUNT | Order amount (not multiplied by 100) |
| CURRENCY | Order currency |
| NCERROR | Error code |
| NCERRORPLUS | Explanation of the error code |
| NCSTATUS | First digit of NCERROR |
| ORDERID | Your order reference |
| PAYID | Payment reference in our system |
| PAYIDSUB |
The history level ID of the maintenance operation on the PAYID |
| STATUS | Transaction status (Possible statuses) |
The standard ncresponse tag attributes are the same as those for the XML reply to a new order, except for the extra attribute PAYIDSUB.
1.3 Duplicate request
If maintenance is requested twice for the same order, the second request will theoretically be declined with an error “50001127” (This order is not authorised), because the initial successful transaction will have changed the order status.
4.1.3 Authorisation and capture
SwissBilling follows a 2-step flow which means that Authorisation and Capture can be separated in the order process. However, only full captures are accepted by SwissBilling.
4.1.4 Refunds
For more information about refunds, see Chapter 3.1 Performing maintenance operations.
4.1.5 Test credentials
Tests are run on SwissBilling. Contact our Merchanthelp to set up an end-to-end testing.Testing has to be done with the MerchantID, Password, and ShopID that was provided at the signing of a contract with SwissBilling.