Documentation
Documentation
Payment Page

1Introduction

In order to create a payment over the platform you have the choice between the payment page integration where the customer is redirected to our payment page, the iframe integration where the payment form is placed in an iframe using our JavaScript integration or the lightbox integration in order to achieve a seamless and PCI DSS compliant integration in your checkout.

The process of the payment page is as follow (simplified):

  1. Create a transaction object via our API.

  2. Request the payment page URL.

  3. Redirect the user to the payment page.

  4. Process the incoming webhook request to authorize the transaction in the merchant application.

2System Interactions

Payment Page Integration
Figure 1. Sequence Diagram of the Payment Page Integration

3Payment Page Integration Details

Before you start with the integration of the payment page you should:

  1. Create an account and sign up.

  2. Create an application user under Account > Users > Application User.

  3. Learn how to authenticate and connect to our web service.

Note
 Please have a look at our github repository where we offer ready to download SDK in different languages that facilitate your integration efforts drastically.

We offer you also an API Client that allows you to test the requests sent to the API and see the responses.

3.1Process

  1. When the customer completes the checkout, create an order in your shop.

  2. You have to create a transaction object using the create method on the Transaction Service.

  3. Use the build payment page URL service to create the payment page URL and redirect the customer to this URL. The customer enters the payment details on the payment page. Based on the payment method he will be further redirected if needed.

  4. When the transaction is processed or failed on our side the customer will be redirected to the successUrl or failedUrl that was defined when creating the transaction object.

  5. Listen to the notification to mark the order in the merchant system as authorized or failed.

You may enhance this process by letting the customer to select the payment method already in the merchant application. We provide with the fetch possible payment methods operation on the Transaction Service the option to fetch the enabled payment methods for a particular space. As we describe here the payment page integration mode you have to pass payment_page as the integration mode.

As a result the method returns the possible payment methods. Those payment methods build the base of the list of payment methods presented to the customer. The property allowedPaymentMethods on the transaction object allows to restrict the allowed payment methods for the particular transaction to the selection done by the customer previously.

3.1.1Create a Transaction Object

In order to create a transaction object you have to use the Transaction Create Operation. Here you provide the customer details that you have including the line items and prices. This will create a pending transaction in your space.

Request

{
   "billingAddress":{
      "city":"Winterthur",
      "commercialRegisterNumber":"",
      "country":"CH",
      "dateOfBirth":"",
      "emailAddress":"[email protected]",
      "familyName":"Test",
      "gender":"",
      "givenName":"Sam",
      "mobilePhoneNumber":"",
      "organisationName":"customweb GmbH",
      "phoneNumber":"",
      "postCode":"8400",
      "salesTaxNumber":"",
      "salutation":"",
      "socialSecurityNumber":"",
      "state":"",
      "street":"General-Guisan-Strasse 47"
   },
   "currency":"EUR",
   "language":"de-CH",
   "lineItems":[
      {
         "amountIncludingTax":"11.87",
         "name":"Barbell Pull Up Bar",
         "quantity":"1",
         "shippingRequired":"true",
         "sku":"barbell-pullup",
         "type":"PRODUCT",
         "uniqueId":"barbell-pullup"
      },
      {
         "amountIncludingTax":"559",
         "name":"Rowing Machine",
         "quantity":"1",
         "shippingRequired":"true",
         "sku":"rowing-machine",
         "type":"PRODUCT",
         "uniqueId":"rowing-machine"
      },
      {
         "amountIncludingTax":"17.98",
         "name":"Super Whey Protein",
         "quantity":"4",
         "shippingRequired":"true",
         "sku":"super-whey",
         "taxes":[
            {
               "rate":"10",
               "title":"VAT"
            },
            {
               "rate":"3.5",
               "title":"Supplement Fee"
            }
         ],
         "type":"PRODUCT",
         "uniqueId":"super-whey"
      },
      {
         "amountIncludingTax":"12.5",
         "name":"Special Chär Test",
         "quantity":"1",
         "shippingRequired":"false",
         "sku":"special-chär-test",
         "type":"SHIPPING",
         "uniqueId":"special-chär-test"
      },
      {
         "amountIncludingTax":"12.5",
         "name":"Standard Shipping",
         "quantity":"1",
         "shippingRequired":"false",
         "sku":"standard-shipping",
         "type":"SHIPPING",
         "uniqueId":"standard-shipping"
      },
      {
         "amountIncludingTax":"-10",
         "name":"Spring Discount",
         "quantity":"1",
         "shippingRequired":"false",
         "sku":"spring-discount",
         "type":"DISCOUNT",
         "uniqueId":"spring-discount"
      }
   ],
   "merchantReference":"DEV-2630",
   "shippingAddress":{
      "city":"Winterthur",
      "commercialRegisterNumber":"",
      "country":"CH",
      "dateOfBirth":"",
      "emailAddress":"[email protected]",
      "familyName":"Test",
      "gender":"",
      "givenName":"Sam",
      "mobilePhoneNumber":"",
      "organisationName":"customweb GmbH",
      "phoneNumber":"",
      "postCode":"8400",
      "salesTaxNumber":"",
      "salutation":"",
      "socialSecurityNumber":"",
      "state":"",
      "street":"General-Guisan-Strasse 47"
   }
}

Response

The response that you will receive contains the id (in the example below 109472) that will now be used to perform further operations with this transactions.

{
	"acceptHeader": null,
	"allowedPaymentMethodBrands": [],
	"allowedPaymentMethodConfigurations": [],
	"authorizationAmount": 603.85,
	"authorizationTimeoutOn": "2017-12-07T08:44:09.119Z",
	"authorizedOn": null,
	"autoConfirmationEnabled": true,
	"billingAddress": {
		"city": "Winterthur",
		"commercialRegisterNumber": "",
		"country": "CH",
		"dateOfBirth": null,
		"dependentLocality": null,
		"emailAddress": "[email protected]",
		"familyName": "Test",
		"gender": null,
		"givenName": "Sam",
		"legalOrganizationForm": null,
		"mobilePhoneNumber": "",
		"organizationName": null,
		"phoneNumber": "",
		"postCode": "8400",
		"postalState": null,
		"salesTaxNumber": "",
		"salutation": "",
		"socialSecurityNumber": "",
		"sortingCode": null,
		"street": "General-Guisan-Strasse 47"
	},
	"chargeRetryEnabled": true,
	"completedOn": null,
	"completionTimeoutOn": null,
	"confirmedBy": 0,
	"confirmedOn": null,
	"createdBy": 0,
	"createdOn": "2017-12-07T08:14:09.119Z",
	"currency": "EUR",
	"customerEmailAddress": null,
	"customerId": null,
	"customersPresence": "VIRTUAL_PRESENT",
	"endOfLife": "2017-12-21T08:14:09.119Z",
	"failedOn": null,
	"failedUrl": null,
	"failureReason": null,
	"group": {
		"beginDate": "2017-12-07T08:14:09.124Z",
		"customerId": null,
		"endDate": "2017-12-07T08:14:09.124Z",
		"id": 109478,
		"linkedSpaceId": 396,
		"plannedPurgeDate": "2017-12-07T08:19:09.124Z",
		"state": "PENDING",
		"version": 1
	},
	"id": 109472,
	"internetProtocolAddress": null,
	"internetProtocolAddressCountry": null,
	"invoiceMerchantReference": null,
	"language": "de-CH",
	"lineItems": [
		{
			"aggregatedTaxRate": 0,
			"amountExcludingTax": 11.87,
			"amountIncludingTax": 11.87,
			"attributes": {},
			"name": "Barbell Pull Up Bar",
			"quantity": 1,
			"shippingRequired": true,
			"sku": "barbell-pullup",
			"taxAmount": 0,
			"taxAmountPerUnit": 0,
			"taxes": [],
			"type": "PRODUCT",
			"uniqueId": "barbell-pullup",
			"unitPriceExcludingTax": 11.87,
			"unitPriceIncludingTax": 11.87
		},
		{
			"aggregatedTaxRate": 0,
			"amountExcludingTax": 559,
			"amountIncludingTax": 559,
			"attributes": {},
			"name": "Rowing Machine",
			"quantity": 1,
			"shippingRequired": true,
			"sku": "rowing-machine",
			"taxAmount": 0,
			"taxAmountPerUnit": 0,
			"taxes": [],
			"type": "PRODUCT",
			"uniqueId": "rowing-machine",
			"unitPriceExcludingTax": 559,
			"unitPriceIncludingTax": 559
		},
		{
			"aggregatedTaxRate": 13.5,
			"amountExcludingTax": 15.84,
			"amountIncludingTax": 17.98,
			"attributes": {},
			"name": "Super Whey Protein",
			"quantity": 4,
			"shippingRequired": true,
			"sku": "super-whey",
			"taxAmount": 2.14,
			"taxAmountPerUnit": 0.54,
			"taxes": [
				{
					"rate": 10,
					"title": "VAT"
				},
				{
					"rate": 3.5,
					"title": "Supplement Fee"
				}
			],
			"type": "PRODUCT",
			"uniqueId": "super-whey",
			"unitPriceExcludingTax": 3.96,
			"unitPriceIncludingTax": 4.5
		},
		{
			"aggregatedTaxRate": 0,
			"amountExcludingTax": 12.5,
			"amountIncludingTax": 12.5,
			"attributes": {},
			"name": "Special Chär Test",
			"quantity": 1,
			"shippingRequired": false,
			"sku": "special-chär-test",
			"taxAmount": 0,
			"taxAmountPerUnit": 0,
			"taxes": [],
			"type": "SHIPPING",
			"uniqueId": "special-chär-test",
			"unitPriceExcludingTax": 12.5,
			"unitPriceIncludingTax": 12.5
		},
		{
			"aggregatedTaxRate": 0,
			"amountExcludingTax": 12.5,
			"amountIncludingTax": 12.5,
			"attributes": {},
			"name": "Standard Shipping",
			"quantity": 1,
			"shippingRequired": false,
			"sku": "standard-shipping",
			"taxAmount": 0,
			"taxAmountPerUnit": 0,
			"taxes": [],
			"type": "SHIPPING",
			"uniqueId": "standard-shipping",
			"unitPriceExcludingTax": 12.5,
			"unitPriceIncludingTax": 12.5
		},
		{
			"aggregatedTaxRate": 0,
			"amountExcludingTax": -10,
			"amountIncludingTax": -10,
			"attributes": {},
			"name": "Spring Discount",
			"quantity": 1,
			"shippingRequired": false,
			"sku": "spring-discount",
			"taxAmount": 0,
			"taxAmountPerUnit": 0,
			"taxes": [],
			"type": "DISCOUNT",
			"uniqueId": "spring-discount",
			"unitPriceExcludingTax": -10,
			"unitPriceIncludingTax": -10
		}
	],
	"linkedSpaceId": 396,
	"merchantReference": "DEV-2630",
	"metaData": {},
	"paymentConnectorConfiguration": null,
	"plannedPurgeDate": "2017-12-21T08:14:09.119Z",
	"processingOn": null,
	"refundedAmount": 0,
	"shippingAddress": {
		"city": "Winterthur",
		"commercialRegisterNumber": "",
		"country": "CH",
		"dateOfBirth": null,
		"dependentLocality": null,
		"emailAddress": "[email protected]",
		"familyName": "Test",
		"gender": null,
		"givenName": "Sam",
		"legalOrganizationForm": null,
		"mobilePhoneNumber": "",
		"organizationName": null,
		"phoneNumber": "",
		"postCode": "8400",
		"postalState": null,
		"salesTaxNumber": "",
		"salutation": "",
		"socialSecurityNumber": "",
		"sortingCode": null,
		"street": "General-Guisan-Strasse 47"
	},
	"shippingMethod": null,
	"spaceViewId": null,
	"state": "PENDING",
	"successUrl": null,
	"timeZone": "Z",
	"token": null,
	"userAgentHeader": null,
	"userFailureMessage": null,
	"userInterfaceType": null,
	"version": 1
}

3.1.2Update Transactions

Transaction properties can be updated as long as they are not in the confirmed state. In order to do this use the update operation on the Transaction service.

Note
 Have a look at the Object Versioning / Locking Section to describe how you have to handle the version property to prevent optimistic locking.

Request

In the example below we are going to update the line items and get rid of the discount line item that we added in the example above.

{
    "billingAddress": {
        "city": "Winterthur",
        "country": "CH",
        "emailAddress": "[email protected]",
        "familyName": "Test",
        "givenName": "Sam",
        "postCode": "8400",
        "street": "General-Guisan-Strasse 47"
    },
    "currency": "EUR",
    "id": 109472,
    "language": "de-CH",
    "lineItems": [
        {
            "amountIncludingTax": "11.87",
            "name": "Barbell Pull Up Bar",
            "quantity": "1",
            "sku": "barbell-pullup",
            "type": "PRODUCT",
            "uniqueId": "barbell-pullup"
        },
        {
            "amountIncludingTax": "559",
            "name": "Rowing Machine",
            "quantity": "1",
            "sku": "rowing-machine",
            "type": "PRODUCT",
            "uniqueId": "rowing-machine"
        },
        {
            "amountIncludingTax": "17.98",
            "name": "Super Whey Protein",
            "quantity": "4",
            "sku": "super-whey",
            "type": "PRODUCT",
            "uniqueId": "super-whey"
        },
        {
            "amountIncludingTax": "12.5",
            "name": "Special Chär Test",
            "quantity": "1",
            "sku": "special-chär-test",
            "type": "SHIPPING",
            "uniqueId": "special-chär-test"
        },
        {
            "amountIncludingTax": "12.5",
            "name": "Standard Shipping",
            "quantity": "1",
            "sku": "standard-shipping",
            "type": "SHIPPING",
            "uniqueId": "standard-shipping"
        }
    ],
    "merchantReference": "DEV-2630",
    "shippingAddress": {
        "city": "Winterthur",
        "country": "CH",
        "emailAddress": "[email protected]",
        "familyName": "Test",
        "givenName": "Sam",
        "postCode": "8400",
        "street": "General-Guisan-Strasse 47"
    },
    "version": 3
}

Response

The response contains the updated transaction object.

{
    "billingAddress": {
        "city": "Winterthur",
        "country": "CH",
        "emailAddress": "[email protected]",
        "familyName": "Test",
        "givenName": "Sam",
        "postCode": "8400",
        "street": "General-Guisan-Strasse 47"
    },
    "currency": "EUR",
    "id": 109472,
    "language": "de-CH",
    "lineItems": [
        {
            "amountIncludingTax": "11.87",
            "name": "Barbell Pull Up Bar",
            "quantity": "1",
            "sku": "barbell-pullup",
            "type": "PRODUCT",
            "uniqueId": "barbell-pullup"
        },
        {
            "amountIncludingTax": "559",
            "name": "Rowing Machine",
            "quantity": "1",
            "sku": "rowing-machine",
            "type": "PRODUCT",
            "uniqueId": "rowing-machine"
        },
        {
            "amountIncludingTax": "17.98",
            "name": "Super Whey Protein",
            "quantity": "4",
            "sku": "super-whey",
            "type": "PRODUCT",
            "uniqueId": "super-whey"
        },
        {
            "amountIncludingTax": "12.5",
            "name": "Special Chär Test",
            "quantity": "1",
            "sku": "special-chär-test",
            "type": "SHIPPING",
            "uniqueId": "special-chär-test"
        },
        {
            "amountIncludingTax": "12.5",
            "name": "Standard Shipping",
            "quantity": "1",
            "sku": "standard-shipping",
            "type": "SHIPPING",
            "uniqueId": "standard-shipping"
        }
    ],
    "merchantReference": "DEV-2630",
    "shippingAddress": {
        "city": "Winterthur",
        "country": "CH",
        "emailAddress": "[email protected]",
        "familyName": "Test",
        "givenName": "Sam",
        "postCode": "8400",
        "street": "General-Guisan-Strasse 47"
    },
    "version": 3
}

3.1.3Realize Payment Preselection

In order to achieve a better integration it helps if you show your customers already in the checkout what payment methods would be available based on the data in the transaction object. The response should be rendered and showed as payment options in your checkout.

In order to preselect the payment method on the transaction you should update the transaction as shown before by providing the allowedPaymentMethodConfiguration id that is returned on the fetchPossiblePaymentMethods for the given transaction.

Response

The response returns the possible payment methods for the given transactionid.

[
	{
		"dataCollectionType": "ONSITE",
		"description": {
			"availableLanguages": [
				"en-US"
			],
			"displayName": "",
			"items": [
				{
					"language": "en-US",
					"languageCode": "en",
					"translation": ""
				}
			]
		},
		"id": 510,
		"imageResourcePath": null,
		"linkedSpaceId": 396,
		"name": "Credit / Debit Card",
		"oneClickPaymentMode": "ALLOW",
		"paymentMethod": 1457546097597,
		"plannedPurgeDate": null,
		"resolvedDescription": {
			"de-DE": "Bezahlen Sie bequem per Kredit- oder Debitkarte.",
			"en-US": "Pay conveniently with your credit or debit card."
		},
		"resolvedImageUrl": "https://checkout.postfinance.ch/s/396/resource/icon/payment/method/credit-debit-card.svg",
		"resolvedTitle": {
			"de-DE": "Kredit- / Debitkarte",
			"en-US": "Credit / Debit Card"
		},
		"sortOrder": 1,
		"spaceId": 396,
		"state": "ACTIVE",
		"title": {
			"availableLanguages": [
				"en-US"
			],
			"displayName": "",
			"items": [
				{
					"language": "en-US",
					"languageCode": "en",
					"translation": ""
				}
			]
		},
		"version": 2
	}
]

Now you can use this information to render the payment method selection in your shop. Once the client chooses the payment method you can update the transaction above by providing the allowedPaymentMethodConfigurations with the update operation on the transaction service.

Request

{
    "allowedPaymentMethodConfigurations": [
        {
            "id": 507
        }
    ],
    "id": 109472,
    "version": 4
}

3.1.4Build Payment Page URL

In order to redirect the client to the payment page you use the Build Payment Page URL operation that returns the URL to the payment page in order to redirect the client to.

Note
 We offer a lot of flexibility to style the look and feel of the payment page using our resource editor. More information can be found in the Resources and Customization Documentation.

3.1.5Fetch Transaction Update

In order to be updated about the transaction state you should register webhook notification on your side. The webhooks will update you about state changes of the selected entities and should trigger your application to further process the transaction results.

More Information about webhooks, webhooks listener and their configuration can be found in the Webhooks Documentation.