Module: Adyen::API

Extended by:
API
Included in:
API
Defined in:
lib/adyen/api.rb,
lib/adyen/api/response.rb,
lib/adyen/api/xml_querier.rb,
lib/adyen/api/test_helpers.rb,
lib/adyen/api/payment_service.rb,
lib/adyen/api/recurring_service.rb,
lib/adyen/api/simple_soap_client.rb,
lib/adyen/api/templates/payment_service.rb,
lib/adyen/api/templates/recurring_service.rb

Overview

The API module contains classes that interact with the Adyen SOAP API.

You'll need to provide a username and password to interact with Adyen:

Adyen.configuration.api_username = 'ws@Company.MyAccount'
Adyen.configuration.api_password = 'secret'

Furthermore, you can setup default parameters, which will be used by every API call, by using default_arguments.

The following classes, which handle the SOAP services, are available:

However, direct use of these classes is discouraged in favor of the shortcut methods defined on the API module. These methods require that you set the :merchant_account beforehand as a default parameter passed in all API calls:

Adyen.configuration.default_api_params[:merchant_account] = 'MerchantAccount'

For Rails apps, you can also set it `application.rb` config block, like this:

config.adyen.default_api_params = { :merchant_account => 'MerchantAccount' }

Note that you'll need an Adyen notification PSP reference for some of the calls. Because of this, store all notifications that Adyen sends to you. Moreover, the responses to these calls do not tell you whether or not the requested action was successful. For this you will also have to check the notification.

Authorising payments

To authorise payments, not recurring ones, the customers payment details will have to pass through your application’s infrastucture. Because of this you will have to contact Adyen and provide the necessary paperwork which says that you’re PCI DSS compliant, before you are given access to Adyen’s API.

Unless you are going to process over twenty thousand payments anually, the PCI DSS Self-Assessment Questionnaire (SAQ) type A will probably suffice.

See Also:

Defined Under Namespace

Classes: PaymentService, RecurringService, Response, SimpleSOAPClient, XMLQuerier

Instance Method Summary (collapse)

Instance Method Details

- (PaymentService::AuthorisationResponse) authorise_one_click_payment(reference, amount, shopper, card_cvc, recurring_detail_reference, fraud_offset = nil)

Authorise a ‘one-click’ payment. A specific contract detail has to be specified.

Of all options, only the shopper’s IP address is optional. But since it’s used in various risk checks, it’s a good idea to supply it anyway.

Examples:

detail  = Adyen::API.list_recurring_details(user.id).details.last[:recurring_detail_reference]
payment = Adyen::API.authorise_one_click_payment(
  invoice.id,
  { :currency => 'EUR', :value => invoice.amount },
  { :reference => user.id, :email => user.email, :ip => '8.8.8.8', :statement => 'invoice number 123456' },
  '737',
  detail
)
payment.authorised? # => true

Parameters:

  • reference (Numeric, String)

    Your reference (ID) for this payment.

  • amount (Hash)

    A hash describing the money to charge.

  • shopper (Hash)

    A hash describing the shopper.

  • card_cvc (String)

    The card’s verification code.

  • recurring_detail_reference (String)

    The recurring contract reference to use.

  • fraud_offset (Numeric) (defaults to: nil)

    Modify Adyen's fraud check by supplying an offset for their calculation.

Options Hash (amount):

  • :currency (String)

    The ISO currency code (EUR, GBP, USD, etc).

  • :value (Integer)

    The value of the payment in discrete cents, unless the currency does not have cents.

Options Hash (shopper):

  • :reference (Numeric, String)

    The shopper’s reference (ID).

  • :email (String)

    The shopper’s email address.

  • :ip (String)

    The shopper’s IP address.

  • :statement (String)

    The shopper's statement

Returns:

See Also:

  • capture_payment
  • list_recurring_details


195
196
197
198
199
200
201
202
203
# File 'lib/adyen/api.rb', line 195

def authorise_one_click_payment(reference, amount, shopper, card_cvc, recurring_detail_reference, fraud_offset = nil)
  params = { :reference => reference,
             :amount    => amount,
             :shopper   => shopper,
             :card      => { :cvc => card_cvc },
             :recurring_detail_reference => recurring_detail_reference,
             :fraud_offset => fraud_offset }
  PaymentService.new(params).authorise_one_click_payment
end

- (PaymentService::AuthorisationResponse) authorise_payment(reference, amount, shopper, card, enable_recurring_contract = false, fraud_offset = nil)

Authorise a payment.

Of all options, only the details are optional. But since the IP is’s used in various risk checks, and the email and reference are needed to enable recurring contract, it’s a good idea to supply it anyway.

Examples:

response = Adyen::API.authorise_payment(
  invoice.id,
  { :currency => 'EUR', :value => invoice.amount },
  { :reference => user.id, :email => user.email, :ip => '8.8.8.8', :statement => 'invoice number 123456'},
  { :holder_name => "Simon Hopper", :number => '4444333322221111', :cvc => '737',
    :expiry_month => 12, :expiry_year => 2012 }
)
response.authorised? # => true

Parameters:

  • reference (Numeric, String)

    Your reference (ID) for this payment.

  • amount (Hash)

    A hash describing the money to charge.

  • shopper (Hash)

    A hash describing the shopper.

  • card (Hash)

    A hash describing the credit card details.

  • enable_recurring_contract (Boolean) (defaults to: false)

    Store the payment details at Adyen for future recurring or one-click payments.

  • fraud_offset (Numeric) (defaults to: nil)

    Modify Adyen's fraud check by supplying an offset for their calculation.

Options Hash (amount):

  • :currency (String)

    The ISO currency code (EUR, GBP, USD, etc).

  • :value (Integer)

    The value of the payment in discrete cents, unless the currency does not have cents.

Options Hash (shopper):

  • :reference (Numeric, String)

    The shopper’s reference (ID).

  • :email (String)

    The shopper’s email address.

  • :ip (String)

    The shopper’s IP address.

  • :statement (String)

    The shopper's statement

Options Hash (card):

  • :holder_name (String)

    The full name on the card.

  • :number (String)

    The card number.

  • :cvc (String)

    The card’s verification code.

  • :expiry_month (Numeric, String)

    The month in which the card expires.

  • :expiry_year (Numeric, String)

    The year in which the card expires.

Returns:

See Also:

  • capture_payment


99
100
101
102
103
104
105
106
107
# File 'lib/adyen/api.rb', line 99

def authorise_payment(reference, amount, shopper, card, enable_recurring_contract = false, fraud_offset = nil)
  params = { :reference    => reference,
             :amount       => amount,
             :shopper      => shopper,
             :card         => card,
             :recurring    => enable_recurring_contract,
             :fraud_offset => fraud_offset }
  PaymentService.new(params).authorise_payment
end

- (PaymentService::AuthorisationResponse) authorise_recurring_payment(reference, amount, shopper, recurring_detail_reference = 'LATEST', fraud_offset = nil)

Authorise a recurring payment. The contract detail will default to the ‘latest’, which is generally what you’d want.

Of all options, only the shopper’s IP address is optional. But since it’s used in various risk checks, it’s a good idea to supply it anyway.

Examples:

response = Adyen::API.authorise_recurring_payment(
  invoice.id,
  { :currency => 'EUR', :value => invoice.amount },
  { :reference => user.id, :email => user.email, :ip => '8.8.8.8', :statement => 'invoice number 123456' }
)
response.authorised? # => true

Parameters:

  • reference (Numeric, String)

    Your reference (ID) for this payment.

  • amount (Hash)

    A hash describing the money to charge.

  • shopper (Hash)

    A hash describing the shopper.

  • recurring_detail_reference (String) (defaults to: 'LATEST')

    The recurring contract reference to use.

  • fraud_offset (Numeric) (defaults to: nil)

    Modify Adyen's fraud check by supplying an offset for their calculation.

Options Hash (amount):

  • :currency (String)

    The ISO currency code (EUR, GBP, USD, etc).

  • :value (Integer)

    The value of the payment in discrete cents, unless the currency does not have cents.

Options Hash (shopper):

  • :reference (Numeric, String)

    The shopper’s reference (ID).

  • :email (String)

    The shopper’s email address.

  • :ip (String)

    The shopper’s IP address.

  • :statement (String)

    The shopper's statement

Returns:

See Also:

  • capture_payment
  • list_recurring_details


146
147
148
149
150
151
152
153
# File 'lib/adyen/api.rb', line 146

def authorise_recurring_payment(reference, amount, shopper, recurring_detail_reference = 'LATEST', fraud_offset = nil)
  params = { :reference => reference,
             :amount    => amount,
             :shopper   => shopper,
             :recurring_detail_reference => recurring_detail_reference,
             :fraud_offset => fraud_offset }
  PaymentService.new(params).authorise_recurring_payment
end

- (PaymentService::CancelOrRefundResponse) cancel_or_refund_payment(psp_reference)

Cancel or refund a payment. Use this if you want to cancel or refund the payment, but are unsure what the current status is.

Note that the response of this request will only indicate whether or not the request has been successfuly received. Check the notitification for the actual mutation status.

Parameters:

  • psp_reference (String)

    The PSP reference, from Adyen, of the previously authorised request.

Returns:



257
258
259
# File 'lib/adyen/api.rb', line 257

def cancel_or_refund_payment(psp_reference)
  PaymentService.new(:psp_reference => psp_reference).cancel_or_refund
end

- (PaymentService::CancelResponse) cancel_payment(psp_reference)

Cancel an authorised payment.

Note that the response of this request will only indicate whether or not the request has been successfuly received. Check the notitification for the actual mutation status.

Parameters:

  • psp_reference (String)

    The PSP reference, from Adyen, of the previously authorised request.

Returns:



271
272
273
# File 'lib/adyen/api.rb', line 271

def cancel_payment(psp_reference)
  PaymentService.new(:psp_reference => psp_reference).cancel
end

- (PaymentService::CaptureResponse) capture_payment(psp_reference, amount)

Capture an authorised payment.

You can also configure your merchant account to automatically capture authorised payments in the merchant account settings.

Note that the response of this request will only indicate whether or not the request has been successfuly received. Check the notitification for the actual mutation status.

Parameters:

  • psp_reference (String)

    The PSP reference, from Adyen, of the previously authorised request.

  • amount (Hash)

    A hash describing the money to charge.

Options Hash (amount):

  • :currency (String)

    The ISO currency code (EUR, GBP, USD, etc).

  • :value (Integer)

    The value of the payment in discrete cents, unless the currency does not have cents.

Returns:

See Also:



224
225
226
# File 'lib/adyen/api.rb', line 224

def capture_payment(psp_reference, amount)
  PaymentService.new(:psp_reference => psp_reference, :amount => amount).capture
end

- (RecurringService::DisableResponse) disable_recurring_contract(shopper_reference, recurring_detail_reference = nil)

Disable the recurring contract details for a shopper.

Parameters:

  • shopper_reference (String)

    The ID used to store payment details for this shopper.

  • recurring_detail_reference (String, nil) (defaults to: nil)

    The ID of a specific recurring contract. Defaults to all.

Returns:



293
294
295
296
297
298
# File 'lib/adyen/api.rb', line 293

def disable_recurring_contract(shopper_reference, recurring_detail_reference = nil)
  RecurringService.new({
    :shopper => { :reference => shopper_reference },
    :recurring_detail_reference => recurring_detail_reference
  }).disable
end

- (RecurringService::ListResponse) list_recurring_details(shopper_reference)

Retrieve the recurring contract details for a shopper.

Parameters:

  • shopper_reference (String)

    The ID used to store payment details for this shopper.

Returns:



281
282
283
# File 'lib/adyen/api.rb', line 281

def list_recurring_details(shopper_reference)
  RecurringService.new(:shopper => { :reference => shopper_reference }).list
end

- (PaymentService::RefundResponse) refund_payment(psp_reference, amount)

Refund a captured payment.

Note that the response of this request will only indicate whether or not the request has been successfuly received. Check the notitification for the actual mutation status.

Parameters:

  • psp_reference (String)

    The PSP reference, from Adyen, of the previously authorised request.

  • amount (Hash)

    A hash describing the money to charge.

Options Hash (amount):

  • :currency (String)

    The ISO currency code (EUR, GBP, USD, etc).

  • :value (Integer)

    The value of the payment in discrete cents, unless the currency does not have cents.

Returns:



242
243
244
# File 'lib/adyen/api.rb', line 242

def refund_payment(psp_reference, amount)
  PaymentService.new(:psp_reference => psp_reference, :amount => amount).refund
end

- (RecurringService::StoreTokenResponse) store_recurring_token(shopper, params)

Stores and tokenises the payment details so that recurring payments can be made in the future. It can be either a credit card or ELV (Elektronisches Lastschriftverfahren).

For instance, this is how you would store credit card details:

# @example

response = Adyen::API.store_recurring_token(
  { :reference => user.id, :email => user.email, :ip => '8.8.8.8', :statement => 'invoice number 123456' },
  { :holder_name => "Simon Hopper", :number => '4444333322221111',
    :expiry_month => 12, :expiry_year => 2012 }
)

Or use the following to store ELV details:

# @example

response = Adyen::API.store_recurring_token(
  { :reference => user.id, :email => user.email, :ip => '8.8.8.8', :statement => 'invoice number 123456' },
  { :bank_location => "Berlin", :bank_name => "TestBank", :bank_location_id => "12345678",
    :holder_name => "Simon Hopper", :number => "1234567890" }
)
response.stored? # => true

# Now we can authorize a payment with the token.
authorize_response = Adyen::API.authorise_recurring_payment(
  invoice.id,
  { :currency => 'EUR', :value => invoice.amount },
  { :reference => user.id, :email => user.email, :ip => '8.8.8.8', :statement => 'invoice number 123456' },
  response.recurring_detail_reference
)
authorize_response.authorised? # => true

##### Credit card specific options:

##### ELV specific options:

Parameters:

  • params (Hash)

    A hash describing the credit card or ELV details.

  • shopper (Hash)

    a customizable set of options

Options Hash (shopper):

  • :reference (Numeric, String)

    The shopper’s reference (ID).

  • :email (String)

    The shopper’s email address.

  • :ip (String)

    The shopper’s IP address.

  • :statement (String)

    The shopper's statement

Options Hash (params):

  • :holder_name (String)

    The full name on the card or of the account holder.

  • :number (String)

    The card or account number.

  • :expiry_month (Numeric, String)

    The month in which the card expires.

  • :expiry_year (Numeric, String)

    The year in which the card expires.

  • :bank_location (String)

    The Bank Location.

  • :bank_name (String)

    The Bank Name.

  • :bank_location_id (Numeric, String)

    The Bank Location ID (Bankleitzahl).

Returns:



355
356
357
358
359
360
361
# File 'lib/adyen/api.rb', line 355

def store_recurring_token(shopper, params)
    payment_method = params.include?(:bank_location_id) ? :elv : :card
    RecurringService.new({
      :shopper => shopper,
      payment_method => params
    }).store_token
end