Project

adyen-ruby-api-library

0.11
A long-lived project that still receives updates
adyen-ruby-api-libraryadyen/adyen-ruby-api-libraryHomepageDocumentationSource CodeBug TrackerWiki
Official Adyen API Library for Ruby. Simplifies integrating with the Adyen API,\ including Checkout, Marketpay, payments, recurring, and payouts. For support please reach out to \ support@adyen.com. If you would like to contribute please submit \ a comment or pull request at https://github.com/Adyen/adyen-ruby-api-library.
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
 Popularity
Downloads
1,532,875
Stars
47
Forks
51
Watchers
13
 Releases
Current version
10.1.0
Total releases
45
First release
2019-02-08
Latest release
2024-12-16
 Issues
Open Issues
2
Closed Issues
30
Total Issues
32
Issue Closure Rate
93%
 Pull Requests
Open Pull Requests
0
Closed Pull Requests
36
Merged Pull Requests
215
Pull Request Acceptance Rate
85%
 Development
Primary Language
Ruby
Licenses
MIT
Average date of last 50 commits
2024-09-08
Reverse Dependencies
0

 Dependencies

Development

activesupport
>= 0
bundler
>= 0
webmock
>= 0

Runtime

faraday
>= 0
 Project Readme

Ruby

Adyen API Library for Ruby

This is the officially supported Ruby library for using Adyen's APIs.

Supported APIs

This library supports the following:

API name API version Description API object
BIN lookup API v54 The BIN Lookup API provides endpoints for retrieving information based on a given BIN. BinLookup
Checkout API v71 Our latest integration for accepting online payments. CheckoutAPI
Configuration API v2 The Configuration API enables you to create a platform where you can onboard your users as account holders and create balance accounts, cards, and business accounts. BalancePlatform
DataProtection API v1 Adyen Data Protection API provides a way for you to process Subject Erasure Requests as mandated in GDPR. Use our API to submit a request to delete shopper's data, including payment details and other related information (for example, delivery address or shopper email) DataProtection
Legal Entity Management API v3 Manage legal entities that contain information required for verification. LegalEntityManagement
Management API v3 Configure and manage your Adyen company and merchant accounts, stores, and payment terminals. Management
Payments API v68 Our classic integration for online payments. Classic Integration API
Payouts API v68 Endpoints for sending funds to your customers. Payout
POS Terminal Management API v1 Endpoints for managing your point-of-sale payment terminals. TerminalManagement
Recurring API v68 Endpoints for managing saved payment details. Recurring
Stored Value API v46 Manage both online and point-of-sale gift cards and other stored-value cards. StoredValue
Transfers API v4 The Transfers API provides endpoints that can be used to get information about all your transactions, move funds within your balance platform or send funds from your balance platform to a transfer instrument. Transfers
Cloud-based Terminal API - Our point-of-sale integration. TerminalCloudAPI
Disputes API v30 You can use the Disputes API to automate the dispute handling process so that you can respond to disputes and chargebacks as soon as they are initiated. The Disputes API lets you retrieve defense reasons, supply and delete defense documents, and accept or defend disputes. Disputes
POS Mobile API v68 The POS Mobile API is used in the mutual authentication flow between an Adyen Android or iOS POS Mobile SDK and the Adyen payments platform. The POS Mobile SDK for Android or iOS devices enables businesses to accept in-person payments using a commercial off-the-shelf (COTS) device like a phone. For example, Tap to Pay transactions, or transactions on a mobile device in combination with a card reader. POS Mobile
Payments App API v1 The Payments App API is used to Board and manage the Adyen Payments App on your Android mobile devices. paymentsApp

For more information, refer to our documentation or the API Explorer.

Prerequisites

Installation

The sole dependency is faraday for HTTP communication. Run the following command to install faraday if you don't already have it:

bundle install

To validate functionality of client and run mock API tests use

bundle install --with development

and

rspec

Documentation

Follow the rest of our guides from the documentation on how to use this library.

Using the library

General use with API key

require 'adyen-ruby-api-library'
adyen = Adyen::Client.new

adyen.api_key = 'AF5XXXXXXXXXXXXXXXXXXXX'
  • Make a Payment
response = adyen.checkout.payments_api.payments({
  :amount => {
    :currency => "EUR",
    :value => 1000
  },
  :reference => "Your order number",
  :paymentMethod => {
    :type => "scheme",
    :encryptedCardNumber => "test_4111111111111111",
    :encryptedExpiryMonth => "test_03",
    :encryptedExpiryYear => "test_2030",
    :encryptedSecurityCode => "test_737"
  },
  :returnUrl => "https://your-company.com/checkout/",
  :merchantAccount => "YourMerchantAccount"
})
  • Change API Version
adyen.checkout.version = 69

Example integration

For a closer look at how our Ruby library works, clone our example integration. This includes commented code, highlighting key features and concepts, and examples of API calls that can be made using the library.

Running the tests

To run the tests use :

bundle install --with development

Using the Cloud Terminal API Integration

In order to submit In-Person requests with Terminal API over Cloud you need to initialize the client in the same way as explained above for Ecommerce transactions:

# Step 1: Require the parts of the module you want to use
require 'adyen-ruby-api-library'

# Step 2: Initialize the client object
adyen = Adyen::Client.new(api_key: 'YOUR_API_KEY', env: :test)

# Step 3: Create the request
serviceID = "123456789"
saleID = "POS-SystemID12345"
POIID = "Your Device Name(eg V400m-123456789)"

# Use a unique transaction for every transaction you perform
transactionID = "TransactionID"

request = 
{
  "SaleToPOIRequest": {
    "MessageHeader": {
      "MessageClass": "Service",
      "MessageCategory": "Payment",
      "MessageType": "Request",
      "ServiceID": serviceID,
      "SaleID": saleID,
      "POIID": POIID,
      "ProtocolVersion": "3.0"
    },
    "PaymentRequest": {
      "SaleData": {
        "SaleTransactionID": {
          "TransactionID": transactionID,
          "TimeStamp": "2023-08-23T09:48:55"
        },
        "SaleToAcquirerData": "eyJhcHBsaWNhdGlvbkluZm8iOnsiYWR5ZW5MaWJyYXJ5Ijp7Im5hbWUiOiJhZ....",
        "TokenRequestedType": "Transaction"
      },
      "PaymentTransaction": {
        "AmountsReq": {
          "Currency": "EUR",
          "RequestedAmount": 10
        }
      }
    }
  }
}

# Step 4: Make the request
response = adyen.terminal_cloud_api.sync(request)

Optional: perform an abort request

To perform an abort request you can use the following example:

abortRequest = 
{
  "MessageHeader": {
    "MessageClass": "Service",
    "MessageCategory": "Abort",
    "MessageType": "Request",
    "ServiceID": serviceID,
    "SaleID": saleID,
    "POIID": POIID,
    "ProtocolVersion": "3.0"
  },
  "AbortRequest": {
    "AbortReason": "MerchantAbort",
    "MessageReference": {
      "MessageCategory": "Payment",
      "SaleID": saleID,
      # Service ID of the payment you're aborting
      "ServiceID": serviceID,
      "POIID": POIID
    }
  }
}

response = adyen.terminal_cloud_api.sync(abortRequest)

Optional: perform a status request

To perform a status request you can use the following example:

statusRequest =
{
  "MessageHeader": {
    "MessageClass": "Service",
    "MessageCategory": "TransactionStatus",
    "MessageType": "Request",
    "ServiceID": serviceID,
    "SaleID": saleID,
    "POIID": POIID,
    "ProtocolVersion": "3.0"
  },
  "TransactionStatusRequest": {
    "ReceiptReprintFlag": true,
    "DocumentQualifier": [
      "CashierReceipt",
      "CustomerReceipt"
    ],
    "MessageReference": {
      "SaleID": saleID,
      # serviceID of the transaction you want the status update for
      "ServiceID": serviceID,
      "MessageCategory": "Payment"
    }
  }
}

response = adyen.terminal_cloud_api.sync(statusRequest)

OAuth usage (for Partners)

If you are using our OAuth service to make API requests on your customer's behalf, and you already got your Access Token as explained in the OAuth Integration Guide, you can setup your Client like in the following example:

adyen = Adyen::Client.new

adyen.oauth_token = "oauth_token"

The APIs available to use through OAuth in this library depend on the OAuth Scopes defined when Registering your OAuth client.

Feedback

We value your input! Help us enhance our API Libraries and improve the integration experience by providing your feedback. Please take a moment to fill out our feedback form to share your thoughts, suggestions or ideas.

Contributing

We encourage you to contribute to this repository, so everyone can benefit from new features, bug fixes, and any other improvements. Have a look at our contributing guidelines to find out how to raise a pull request.

Support

If you have a feature request, or spotted a bug or a technical problem, create an issue here.

For other questions, contact our Support Team.

Licence

This repository is available under the MIT license.

See also