bundle add paypal-rest-api
There are two options:
# in config/initializers/paypal_rest_api.rb
PaypalAPI.client = PaypalAPI::Client.new(
client_id: ENV['PAYPAL_CLIENT_ID'],
client_secret: ENV['PAYPAL_CLIENT_SECRET'],
live: false
)
# in your business logic
PaypalAPI.live? # => false
PaypalAPI.api_url # => "https://api-m.sandbox.paypal.com"
PaypalAPI.web_url # => "https://sandbox.paypal.com"
response = PaypalAPI::Orders.show(order_id)
response = PaypalAPI::Orders.create(body: body)
# in your business logic
client = PaypalAPI::Client.new(
client_id: ENV['PAYPAL_CLIENT_ID'],
client_secret: ENV['PAYPAL_CLIENT_SECRET'],
live: false
)
client.live? # => false
client.api_url # => "https://api-m.sandbox.paypal.com"
client.web_url # => "https://sandbox.paypal.com"
response = client.orders.show(order_id)
response = client.orders.create(body: body)
Client can call HTTP methods directly:
response = client.post(path, query: query, body: body, headers: headers)
response = client.get(path, query: query, body: body, headers: headers)
response = client.patch(path, query: query, body: body, headers: headers)
response = client.put(path, query: query, body: body, headers: headers)
response = client.delete(path, query: query, body: body, headers: headers)
# Or, after setting global client:
response = PaypalAPI.post(path, query: query, body: body, headers: headers)
response = PaypalAPI.get(path, query: query, body: body, headers: headers)
response = PaypalAPI.patch(path, query: query, body: body, headers: headers)
response = PaypalAPI.put(path, query: query, body: body, headers: headers)
response = PaypalAPI.delete(path, query: query, body: body, headers: headers)
Response object is returned after each API request.
response.http_status - response HTTP status as Integerresponse.http_body - response body as Stringresponse.http_headers - response headers as Hash with String keysresponse.http_response - original Net::HTTP::Response objectresponse.request - Request object that was used to get this responseresponse.body - parsed JSON body, keys are Symbolsresponse[:field] - gets :field attribute from parsed body,
returns nil if response have no such keyresponse.fetch(:field) - gets :field attribute from parsed body,
raises KeyError if response has no such keyresponse.success? - checks HTTP status code is 2xxresponse.failed? - checks HTTP status code is not 2xxresponse.follow_up_link('approve', query: nil, body: nil, headers: nil) -
Finds HATEOAS link is response with rel=approve and requests it. Returns
nil if no such link were found.response.each_page { |response| ... } - iterates over each page in responseresponse.each_page_item(items_field) { |item| ... } - iterates over each
page itemPaypalAPI client accepts this additional options:
:live:retries,:http_opts:cache:livePaypalAPI client can be defined with live option which is false by default.
When live is false all requests will be send to the sandbox endpoints.
client = PaypalAPI::Client.new(
live: true
# ...
)
:retriesThis is a Hash with retries configuration.
By default retries are enabled, 4 retries with 0, 0.25, 0.75, 1.5 seconds delay.
Default config: {enabled: true, count: 4, sleep: [0, 0.25, 0.75, 1.5]}.
New options are merged with defaults.
Please keep sleep array same size as count.
Retries happen on any network error, on 409, 429, 5xx response status code.
client = PaypalAPI::Client.new(
retries: {enabled: !Rails.env.test?, count: 5, sleep: [0, 0.25, 0.75, 1.5, 2]}
# ...
)
:http_optsThis are the options that are provided to the Net::HTTP.start method,
like :read_timeout, :write_timeout, etc.
You can find full list of available options here https://docs.ruby-lang.org/en/master/Net/HTTP.html#method-c-start (Please choose you version of ruby).
By default it is an empty hash.
client = PaypalAPI::Client.new(
http_opts: {read_timeout: 30, write_timeout: 30, open_timeout: 30}
# ...
)
:cacheThis option can be added to save certificates to between redeploys to validate
webhooks offline. By default this gem has only in-memory caching.
Cache object must response to standard caching #fetch(key, &block) method.
By default it is nil, so downloaded certificates will be downloaded again after
redeploys.
client = PaypalAPI::Client.new(
cache: Rails.cache
# ...
)
PayPal provides HATEOAS links in responses. This links can contain items with
rel=next attribute. We request next pages using this links.
We have two specific methods:
Response#each_page - iterates over each page Response objectResponse#each_page_item(items_field_name) - iterates over items on each pageExample:
PaypalAPI::WebhookEvents.list(page_size: 25).each_page do |response|
# ...
end
PaypalAPI::WebhookEvents.list(page_size: 25).each_page_item(:events) do |hash|
# ...
end
Webhooks can be verified offline
or online.
Method PaypalAPI.verify_webhook(webhook_id:, headers:, raw_body:)
verifies webhook. It verifies webhook OFFLINE and fallbacks
to ONLINE if initial verification returns false to be sure you don't miss a
valid webhook.
When some required header is missing the
PaypalAPI::WebhooksVerifier::MissingHeader error will be raised.
Example of Rails controller with webhook verification:
class Webhooks::PaypalController < ApplicationController
def create
# PayPal registered webhook ID for current URL
webhook_id = ENV['PAYPAL_WEBHOOK_ID']
headers = request.headers # must be a Hash
raw_body = request.raw_post # must be a raw String body
webhook_is_valid = PaypalAPI.verify_webhook(
webhook_id: webhook_id,
headers: headers,
raw_body: raw_body
)
if webhook_is_valid
handle_valid_webhook_event(body)
else
handle_invalid_webhook_event(webhook_id, headers, body)
end
head :no_content
end
end
Callbacks list:
:before - Runs before request:after_success - Runs after getting successful response:after_fail - Runs after getting failed response (non-2xx) status code:after_network_error - Runs after getting network errorCallbacks are registered on client object.
Each callback receive request and context variables.
context can be modified manually to save state between callbacks.
Arguments:
:before - (request, context):after_success - (request, context, response):after_fail - (request, context, response):after_network_error - (request, context, error)Context argument contains retries_enabled and retries_count and
retry_number keys by default.
Examples:
PaypalAPI.client.add_callback(:before) do |request, context|
context[:request_id] = SecureRandom.hex(3)
context[:starts_at] = Process.clock_gettime(Process::CLOCK_MONOTONIC)
end
PaypalAPI.client.add_callback(:after_success) do |request, context, response|
ends_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
duration = ends_at - context[:starts_at]
SomeLogger.debug(
'PaypalAPI success request',
method: request.method,
uri: request.uri.to_s,
duration: duration
)
end
PaypalAPI.client.add_callback(:after_fail) do |request, context, response|
SomeLogger.error(
'PaypalAPI request failed',
method: request.method,
uri: request.uri.to_s,
response_status: response.http_status,
response_body: response.http_body,
will_retry: context[:will_retry],
retry_number: context[:retry_number],
retry_count: context[:retry_count]
)
end
PaypalAPI.client.add_callback(:after_network_error) do |request, context, error|
SomeLogger.error(
'PaypalAPI network connection error',
method: request.method,
uri: request.uri.to_s,
error: error.message,
paypal_request_id: request.headers['paypal-request-id'],
will_retry: context[:will_retry],
retry_number: context[:retry_number],
retry_count: context[:retry_count]
)
end
All APIs can raise error in case of network error or non-2xx response status code.
Errors structure:
PaypalAPI::Error
PaypalAPI::Errors::NetworkError - any network errorPaypalAPI::Errors::FailedRequest - any non-2xx code error
PaypalAPI::Errors::BadRequestPaypalAPI::Errors::UnauthorizedPaypalAPI::Errors::ForbiddenPaypalAPI::Errors::NotFoundPaypalAPI::Errors::MethodNotAllowedPaypalAPI::Errors::NotAcceptablePaypalAPI::Errors::ConflictPaypalAPI::Errors::UnsupportedMediaTypePaypalAPI::Errors::UnprocessableEntityPaypalAPI::Errors::TooManyRequestsPaypalAPI::Errors::FatalError
PaypalAPI::Errors::InternalServerErrorPaypalAPI::Errors::ServiceUnavailableAll errors have additional methods:
#paypal_request_id - PayPal-Request-Id header sent with request#response - Original response object, can be nil in case of NetworkError#request - Original request object#error_name - Original error name#error_message - Original PayPal error :message or error :description#error_debug_id - Paypal debug_id found in response#error_details - Parsed PayPal error details found in parsed response
(with symbolized keys)begin
response = PaypalAPI.authorized_payments.capture(authorization_id, body: body)
rescue PaypalAPI::Error => error
YourLogger.error(
error,
context: {
paypal_request_id: error.paypal_request_id,
error_name: error.error_name,
error_message: error.error_message,
error_debug_id: error.error_debug_id,
error_details: error.error_details
}
)
# `error.request` and `error.response` methods can be used also
end
All API endpoints accept this parameters:
resource_id - Resource ID (Unless create/list endpoint)query - Hash with request query paramsbody - Hash with request body paramsheaders - Hash with request headersPaypalAPI::Orders.createPaypalAPI::Orders.showPaypalAPI::Orders.updatePaypalAPI::Orders.confirmPaypalAPI::Orders.authorizePaypalAPI::Orders.capturePaypalAPI::Orders.trackPaypalAPI::Orders.update_trackerPaypalAPI::PaymentTokens.createPaypalAPI::PaymentTokens.listPaypalAPI::PaymentTokens.showPaypalAPI::PaymentTokens.deletePaypalAPI::SetupTokens.createPaypalAPI::SetupTokens.showPaypalAPI::AuthorizedPayments.showPaypalAPI::AuthorizedPayments.capturePaypalAPI::AuthorizedPayments.reauthorizePaypalAPI::AuthorizedPayments.voidPaypalAPI::CapturedPayments.showPaypalAPI::CapturedPayments.refundPaypalAPI::Refunds.showPaypalAPI::Webhooks.createPaypalAPI::Webhooks.listPaypalAPI::Webhooks.showPaypalAPI::Webhooks.updatePaypalAPI::Webhooks.deletePaypalAPI::Webhooks.event_typesPaypalAPI::Webhooks.verifyPaypalAPI::WebhookEvents.availablePaypalAPI::WebhookEvents.listPaypalAPI::WebhookEvents.showPaypalAPI::WebhookEvents.resendPaypalAPI::WebhookEvents.simulatePaypalAPI::WebhookLookups.createPaypalAPI::WebhookLookups.listPaypalAPI::WebhookLookups.showPaypalAPI::WebhookLookups.deletePaypalAPI::Subscriptions.createPaypalAPI::Subscriptions.showPaypalAPI::Subscriptions.updatePaypalAPI::Subscriptions.revisePaypalAPI::Subscriptions.suspendPaypalAPI::Subscriptions.cancelPaypalAPI::Subscriptions.activatePaypalAPI::Subscriptions.capturePaypalAPI::Subscriptions.transactionsPaypalAPI::SubscriptionPlans.createPaypalAPI::SubscriptionPlans.listPaypalAPI::SubscriptionPlans.showPaypalAPI::SubscriptionPlans.updatePaypalAPI::SubscriptionPlans.activatePaypalAPI::SubscriptionPlans.deactivatePaypalAPI::SubscriptionPlans.update_pricingPaypalAPI::ShipmentTracking.addPaypalAPI::ShipmentTracking.updatePaypalAPI::ShipmentTracking.showPaypalAPI::CatalogProducts.createPaypalAPI::CatalogProducts.listPaypalAPI::CatalogProducts.showPaypalAPI::CatalogProducts.updatePaypalAPI::Disputes.appealPaypalAPI::Disputes.make_offerPaypalAPI::Disputes.showPaypalAPI::Disputes.updatePaypalAPI::Disputes.send_messagePaypalAPI::Disputes.provide_supporting_infoPaypalAPI::Disputes.update_statusPaypalAPI::Disputes.deny_offerPaypalAPI::Disputes.provide_evidencePaypalAPI::Disputes.settlePaypalAPI::Disputes.acknowledge_return_itemPaypalAPI::Disputes.accept_claimPaypalAPI::Disputes.listPaypalAPI::Disputes.escalatePaypalAPI::Disputes.accept_offerPaypalAPI::UserInfo.showPaypalAPI::Users.createPaypalAPI::Users.listPaypalAPI::Users.showPaypalAPI::Users.updatePaypalAPI::Users.deletePaypalAPI::Invoices.createPaypalAPI::Invoices.listPaypalAPI::Invoices.showPaypalAPI::Invoices.updatePaypalAPI::Invoices.deletePaypalAPI::Invoices.searchPaypalAPI::Invoices.remindPaypalAPI::Invoices.delete_refundPaypalAPI::Invoices.delete_paymentPaypalAPI::Invoices.record_refundPaypalAPI::Invoices.record_paymentPaypalAPI::Invoices.send_invoicePaypalAPI::Invoices.cancelPaypalAPI::Invoices.generate_qr_codePaypalAPI::Invoices.generate_invoice_numberPaypalAPI::InvoiceTemplates.createPaypalAPI::InvoiceTemplates.listPaypalAPI::InvoiceTemplates.showPaypalAPI::InvoiceTemplates.updatePaypalAPI::InvoiceTemplates.deletePaypalAPI::Payouts.createPaypalAPI::Payouts.showPaypalAPI::PayoutItems.showPaypalAPI::PayoutItems.cancelPaypalAPI::ReferencedPayouts.createPaypalAPI::ReferencedPayouts.showPaypalAPI::ReferencedPayoutItems.createPaypalAPI::ReferencedPayoutItems.showPaypalAPI::PartnerReferrals.createPaypalAPI::PartnerReferrals.showPaypalAPI::PaymentExperienceWebProfiles.createPaypalAPI::PaymentExperienceWebProfiles.listPaypalAPI::PaymentExperienceWebProfiles.showPaypalAPI::PaymentExperienceWebProfiles.replacePaypalAPI::PaymentExperienceWebProfiles.updatePaypalAPI::PaymentExperienceWebProfiles.deletePaypalAPI::TransactionSearch.list_transactionsPaypalAPI::TransactionSearch.list_all_balances rubocop
rspec
mdl README.md CHANGELOG.md RELEASE.md
Bug reports and pull requests are welcome on GitHub at https://github.com/aglushkov/paypal-rest-api.
The gem is available as open source under the terms of the MIT License.
FAQs
Unknown package
We found that paypal-rest-api 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.
Security News
PyPI confirms no security flaws were exploited in the Ultralytics supply chain attack and highlights improvements for safer package publishing.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.