The defra-ruby-govpay gem facilitates seamless integration with GovPay services, specifically tailored for DEFRA's WCR and WEX applications. It aims to abstract the integration code, offering a flexible and adaptable solution that requires minimal assumptions about the application's data models.

1. Installation
2. Configuration
3. Usage
4. Webhook Handling
5. Error Handling
6. Testing

Add this line to your application's Gemfile:

gem 'defra-ruby-govpay'

And then execute

bundle install

Or install it yourself as:

gem install defra-ruby-govpay

Before you start using the gem, you need to configure it according to your requirements. Create an initializer file (e.g., config/initializers/govpay.rb) and set the necessary parameters:

DefraRubyGovpay.configure do |config|
  config.govpay_url = 'https://your-govpay-url.com'
  config.govpay_front_office_api_token = 'your-front-office-token'
  config.govpay_back_office_api_token = 'your-back-office-token'
  # ... any other configurations
end

Here is a detailed guide on how to use the various components of the defra-ruby-govpay gem in your application:

You can send requests to the GovPay API using the send_request method. Here's an example:

After having followed the configuration step, create an API instance. This has a mandatory parameter to indicate whether the host is a back-office application, in which case any payments it creates will be flagged as MOTO.

govpay_api = DefraRubyGovpay::API.new(host_is_back_office: false)

begin
  response = govpay_api.send_request(
    method: :get,
    path: '/path/to/endpoint',
    params: { param1: 'value1', param2: 'value2' },
    is_moto: false
  )
  puts "Response received: #{response}"
rescue DefraRubyGovpay::GovpayApiError => e
  puts "An error occurred: #{e.message}"
end

Errors are handled through the DefraRubyGovpay::GovpayApiError class. Here's an example of how you can handle errors:

begin
  # some code that might raise an error
rescue DefraRubyGovpay::GovpayApiError => e
  puts "An error occurred: #{e.message}"
end

The gem provides functionality for handling Govpay webhooks for both payments and refunds. The webhook services validate the webhook content, that the status transition is allowed, return structured information that your application can use to update its records.

The webhook services extract and return data from the webhook payload:

# For payment webhooks
result = DefraRubyGovpay::WebhookPaymentService.run(webhook_body)
# => { id: "hu20sqlact5260q2nanm0q8u93", status: "success" }

# For refund webhooks
result = DefraRubyGovpay::WebhookRefundService.run(webhook_body)
# => { id: "789", payment_id: "original-payment-123", status: "success" }

To validate the signature of a webhook, use the CallbackValidator class:

valid = DefraRubyGovpay::CallbackValidator.call(
  request_body,
  ENV['GOVPAY_WEBHOOK_SIGNING_SECRET'],
  request.headers['Pay-Signature']
)

if valid
  # Process the webhook
else
  # Handle invalid signature
end

The gem can handle both payment and refund webhooks:

• Payment Webhooks: These have a resource_type of "payment" and contain payment status information in resource.state.status.
• Refund Webhooks: These have a refund_id field and contain refund status information in the status field.

The appropriate service class will be used based on the webhook type:

• WebhookPaymentService for payment webhooks
• WebhookRefundService for refund webhooks

bundle exec rspec