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):
Create a transaction object
via our API.
Request the payment page URL.
Redirect the user to the payment page.
Process the incoming webhook request to authorize the transaction in the merchant application.
Before you start with the integration of the payment page you should:
Create an account and sign up.
Create an application user under Account > Users > Application User.
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.
When the customer completes the checkout, create an order in your shop.
You have to create a transaction object
using the create
method on the Transaction Service
.
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.
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.
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.
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
}
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
}
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
}
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. |
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.