Welcome to the Ruby SDK for the PAYONE Commerce Platform (api-version 1.35.0)! This repository contains a powerful, easy-to-use software development kit (SDK) designed to simplify the integration of online payment processing into your applications.
This SDK requires Ruby 3.2 or later.
gem install pcp-server-ruby-sdk
To use this SDK you need to construct a PCPServerSDK::CommunicatorConfiguration which encapsulate everything needed to connect to the PAYONE Commerce Platform.
require 'pcp-server-ruby-sdk'
api_key = ENV['API_KEY']
api_secret = ENV['API_SECRET']
communicator_configuration = PCPServerSDK::CommunicatorConfiguration.new(
api_key,
api_secret,
'https://api.preprod.commerce.payone.com'
)
With the configuration you can create an API client for each reource you want to interact with. For example to create a commerce case you can use the PCPServerSDK::Endpoints::CommerceCaseApiClient.
require 'pcp-server-ruby-sdk'
client = PCPServerSDK::Endpoints::CommerceCaseApiClient.new(communicator_configuration)
All payloads and reponses are availabe as ruby classes within the pcp-server-ruby-sdk package. The serialization and deserialization is handled by the SDK internally. For example, to create an empty commerce case you can pass a PCPServerSDK::Models::CreateCommerceCaseRequest instance:
createCommerceCaseRequest = PCPServerSDK::Models::CreateCommerceCaseRequest.new
createCommerceCaseResponse = client.create_commerce_case_request('merchant_id', createCommerceCaseRequest);
The models directly map to the API as described in PAYONE Commerce Platform API Reference. For an in depth example you can take a look at the demo app.
To interact with certain client-side SDKs (such as the credit card tokenizer), you need to generate a short-lived authentication JWT token for your merchant. This token can be retrieved using the SDK as follows:
require 'pcp-server-ruby-sdk'
authentication_client = PCPServerSDK::Endpoints::AuthenticationApiClient.new(communicator_configuration)
token = authentication_client.get_authentication_tokens(merchant_id)
puts "JWT Token: #{token.token}"
puts "Token ID: #{token.id}"
puts "Created: #{token.creation_date}"
puts "Expires: #{token.expiration_date}"
This token can then be used for secure operations such as initializing the credit card tokenizer or other client-side SDKs that require merchant authentication. The token is valid for a limited time (10 minutes) and should be handled securely.
Note: The get_authentication_tokens method requires a valid merchant_id. Optionally, you can provide an X-Request-ID header for tracing requests.
When making a request any client may throw a PCPServerSDK::Errors::ApiException. There two subtypes of this exception:
PCPServerSDK::Errors::ApiErrorReponseException: This exception is thrown when the API returns an well-formed error response. The given errors are deserialized into PCPServerSDK::Models::APIError objects which are availble via the get_errors method on the exception. They usually contain useful information about what is wrong in your request or the state of the resource.PCPServerSDK::Errors::ApiResponseRetrievalException: This exception is a catch-all exception for any error that cannot be turned into a helpful error response. This includes malformed responses or unknown responses.Network errors are not wrap, you can should handle the standard IOExeption.
The SDK allows you to customize the underlying HTTP client used for API requests. This provides flexibility to configure timeouts, SSL settings, proxies, and other HTTP-specific options according to your application's needs.
You can set a global HTTP client that will be used by all API clients:
require 'pcp-server-ruby-sdk'
# Option 1: Using a custom Net::HTTP instance
custom_http = Net::HTTP.new('api.preprod.commerce.payone.com', 443)
custom_http.use_ssl = true
custom_http.read_timeout = 30
custom_http.open_timeout = 10
communicator_configuration = PCPServerSDK::CommunicatorConfiguration.new(
api_key,
api_secret,
'https://api.preprod.commerce.payone.com',
custom_http
)
# Option 2: Using a factory proc for dynamic client creation
http_factory = proc do |uri|
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = uri.scheme == 'https'
http.read_timeout = 60
http.open_timeout = 15
# Add custom headers, proxy settings, etc.
http
end
communicator_configuration = PCPServerSDK::CommunicatorConfiguration.new(
api_key,
api_secret,
'https://api.preprod.commerce.payone.com',
http_factory
)
# Option 3: Set after initialization
communicator_configuration.http_client = custom_http
You can also set HTTP clients for individual API clients, which will override the global configuration:
require 'pcp-server-ruby-sdk'
# Create a specific HTTP client for this API client
commerce_case_http = Net::HTTP.new('api.preprod.commerce.payone.com', 443)
commerce_case_http.use_ssl = true
commerce_case_http.read_timeout = 45
# Pass it to the API client constructor
commerce_case_client = PCPServerSDK::Endpoints::CommerceCaseApiClient.new(
communicator_configuration,
commerce_case_http
)
# Or set it after initialization
commerce_case_client.http_client = commerce_case_http
The SDK uses the following priority order when determining which HTTP client to use:
For advanced use cases, you can provide a factory (Proc or any callable object) that creates HTTP clients dynamically:
# Factory that creates clients with different configurations based on the URI
adaptive_factory = proc do |uri|
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = uri.scheme == 'https'
# Configure based on environment or URI
if uri.host.include?('preprod')
http.read_timeout = 60 # Longer timeout for preprod
else
http.read_timeout = 30 # Standard timeout for production
end
http
end
communicator_configuration.http_client = adaptive_factory
This customization allows you to:
For most payment methods some information from the client is needed, e.g. payment information given by Apple when a payment via ApplePay suceeds. PAYONE provides client side SDKs which helps you interact the third party payment providers. You can find the SDKs under the PAYONE GitHub organization. Either way ensure to never store or even send credit card information to your server. The PAYONE Commerce Platform never needs access to the credit card information. The client side is responsible for safely retrieving a credit card token. This token must be used with this SDK.
When a client is successfully made a payment via ApplePay it receives a ApplePayPayment. This structure is accessible as the PCPServerSDK::Models::ApplePayPayment class. You can use the PCPServerSDK::Transformer::ApplePayTransformer to map an PCPServerSDK::Models::ApplePayPayment to a PCPServerSDK::Models::MobilePaymentMethodSpecificInput which can be used for payment executions or order requests. The transformer has a static method PCPServerSDK::Transformer::transformApplePayPaymentToMobilePaymentMethodSpecificInput which takes an PCPServerSDK::Models::ApplePayPayment and returns a PCPServerSDK::Models::MobilePaymentMethodSpecificInput. The transformer does not check if the response is complete, if anything is missing the field will be set to null.
require 'pcp-server-ruby-sdk'
payment = PCPServerSDK::Models::ApplePayPayment.new(get_json_string_from_request_somehow)
# input is of type PCPServerSDK::Models::MobilePaymentMethodSpecificInput
input = PCPServerSDK::Transformer::transformApplePayPaymentToMobilePaymentMethodSpecificInput(payment)
API_KEY=api_key API_SECRET=api_secret MERCHANT_ID=123 COMMERCE_CASE_ID=234 CHECKOUT_ID=345 ./scripts.sh run
See Contributing
git checkout -b release/0.1.0
scripts.sh script to set correct version./scripts.sh version 0.1.0
When calling the ./scripts.sh version script, the changelog will now be generated automatically using conventional-changelog.
Conventional Commit Messages:
type(scope): subject.Enforcing Commit Messages:
Automatic Changelog Generation:
./scripts.sh version script will automatically generate and update the CHANGELOG.md file.develop branchdevelop in main branchAfter successfully merging all changes to the main branch, an admin can trigger a GitHub Action to finalize and publish the release. This action ensures that the release process is automated, consistent, and deploys the new release from the main branch.
Triggering the GitHub Action:
main branch.main branch.Once the release has been published to PyPi, developers can start using the latest version of the SDK. However, if you want to make the release more visible and include detailed release notes, you can optionally create a GitHub release.
v0.1.0).v0.1.0 - Initial Release).Creating a GitHub release is optional, but it can provide additional context and visibility for your users. For detailed guidance, refer to the GitHub documentation on managing releases.
This project is licensed under the MIT License - see the LICENSE file for details.
Thank you for using our SDK for Online Payments! If you have any questions or need further assistance, feel free to open an issue or contact us.
FAQs
Unknown package
We found that pcp-server-ruby-sdk demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Four npm packages disguised as cryptographic tools steal developer credentials and send them to attacker-controlled Telegram infrastructure.
Security News
Ruby maintainers from Bundler and rbenv teams are building rv to bring Python uv's speed and unified tooling approach to Ruby development.
Security News
Following last week’s supply chain attack, Nx published findings on the GitHub Actions exploit and moved npm publishing to Trusted Publishers.