The PostFinance Checkout Ruby library wraps around the PostFinance Checkout API. This library facilitates your interaction with various services such as transactions, accounts, and subscriptions.
PostFinance Checkout Web Service API
- Ruby 3.0.0+
$ gem install postfinancecheckout-ruby-sdk
The library needs to be configured with your account's space id, user id, and secret key which are available in your PostFinance Checkout
account dashboard. Set space_id
, user_id
, and api_secret
to their values. You can also optionally set default_headers
to set some headers that will be sent to all requests:
require 'postfinancecheckout-ruby-sdk'
space_id = 405
app_user_id = 512
app_user_key = "FKrO76r5VwJtBrqZawBspljbBNOxp5veKQQkOnZxucQ="
# default_headers is an optional param, that represents headers sent to all requests
# timeout is an optional param, that allows to configure custom timeout (default is 25 seconds)
PostFinanceCheckout.configure do |config|
config.user_id = app_user_id
config.authentication_key = app_user_key
config.default_headers = {"x-meta-custom-header": 'value-1', "x-meta-custom-header-2": 'value-2'}
config.timeout = 60
end
# TransactionService
transaction_service = PostFinanceCheckout::TransactionService.new
# TransactionPaymentPageService
transaction_payment_page_service = PostFinanceCheckout::TransactionPaymentPageService.new
To get stated with sending transactions you can review the example below:
require 'postfinancecheckout-ruby-sdk'
space_id = 405
app_user_id = 512
app_user_key = "FKrO76r5VwJtBrqZawBspljbBNOxp5veKQQkOnZxucQ="
# timeout is an optional param, that allows to configure custom timeout (default is 25 seconds)
PostFinanceCheckout.configure do |config|
config.user_id = app_user_id
config.authentication_key = app_user_key
config.timeout = 60
end
# TransactionService
transaction_service = PostFinanceCheckout::TransactionService.new
# TransactionPaymentPageService
transaction_payment_page_service = PostFinanceCheckout::TransactionPaymentPageService.new
transaction = PostFinanceCheckout::TransactionCreate.new({
billingAddress: PostFinanceCheckout::AddressCreate.new({
city: "City",
country: "US",
emailAddress: "[email protected]",
familyName: "Family",
givenName: "Given",
postCode: "98100",
postalState: "WA",
street: "Street"
}),
currency: 'EUR',
customerEmailAddress: "[email protected]",
customerPresence: PostFinanceCheckout::CustomersPresence::VIRTUAL_PRESENT,
failedUrl: "http://localhost/failure",
invoiceMerchantReference: "order-1",
language: "en_US",
lineItems: [
PostFinanceCheckout::LineItemCreate.new({
amountIncludingTax: 29.60,
name: "Item 1",
quantity: 1,
shippingRequired: true,
sku: "sku-1",
taxes: [
PostFinanceCheckout::TaxCreate.new({
rate: 8,
title: "VAT"
})
],
type: PostFinanceCheckout::LineItemType::PRODUCT,
uniqueId: "unique-id-item-1",
}),
PostFinanceCheckout::LineItemCreate.new({
amountIncludingTax: 5.60,
name: "Test Shipping",
quantity: 1,
shippingRequired: false,
sku: "test-shipping",
taxes: [
PostFinanceCheckout::TaxCreate.new({
rate: 8,
title: "VAT"
})
],
type: PostFinanceCheckout::LineItemType::SHIPPING,
uniqueId: "unique-id-shipping-1",
}),
],
merchantReference: "order-1",
shippingAddress: PostFinanceCheckout::AddressCreate.new({
city: "City",
country: "US",
emailAddress: "[email protected]",
familyName: "Family",
givenName: "Given",
postCode: "98100",
postalState: "WA",
street: "Street"
}),
shippingMethod: "Test Shipping",
successUrl: "http://localhost/success"
})
transaction = transaction_service.create(space_id, transaction)
payment_page_url = transaction_payment_page_service.payment_page_url(space_id, transaction.id)
# redirect to payment_page_url
The HTTP request which is sent for a state change of an entity now includes an additional field state
, which provides information about the update of the monitored entity's state. This enhancement is a result of the implementation of our webhook encryption mechanism.
Payload field state
provides direct information about the state update of the entity, making additional API calls to retrieve the entity state redundant.
The provided pseudocode is intentionally generic and serves to illustrate the process of enhancing your API to leverage webhook payload signing. It is not a complete implementation.
Please ensure that you adapt and extend this code to meet the specific needs of your application, including appropriate security measures and error handling. For a detailed webhook payload signing mechanism understanding we highly recommend referring to our comprehensive Webhook Payload Signing Documentation.
post '/webhook/callback' do
request_payload = request.body.read
signature = request.env['HTTP_X_SIGNATURE']
if signature.nil? || signature.empty?
# Make additional API call to retrieve the entity state
# ...
else
if webhook_encryption_service.is_content_valid(signature, request_payload)
# Parse request_payload to extract 'state' value
# Process entity's state change
# ...
end
end
# Process the received webhook data
# ...
end
Please see the license file for more information.