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)

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.

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:

  • (PaymentService::AuthorisationResponse) —

    The response object which holds the authorisation status.

See Also:

  • capture_payment
  • list_recurring_details


186
187
188
189
190
191
192
193
194
 
# File 'lib/adyen/api.rb', line 186

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

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

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.

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:

  • (PaymentService::AuthorisationResponse) —

    The response object which holds the authorisation status.

See Also:

  • capture_payment


96
97
98
99
100
101
102
103
104
 
# File 'lib/adyen/api.rb', line 96

def authorise_payment(reference, amount, shopper, card, enable_recurring_contract = false)
  PaymentService.new(
    :reference => reference,
    :amount    => amount,
    :shopper   => shopper,
    :card      => card,
    :recurring => enable_recurring_contract
  ).authorise_payment
end

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

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.

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:

  • (PaymentService::AuthorisationResponse) —

    The response object which holds the authorisation status.

See Also:

  • capture_payment
  • list_recurring_details


140
141
142
143
144
145
146
147
 
# File 'lib/adyen/api.rb', line 140

def authorise_recurring_payment(reference, amount, shopper, recurring_detail_reference = 'LATEST')
  PaymentService.new(
    :reference => reference,
    :amount    => amount,
    :shopper   => shopper,
    :recurring_detail_reference => recurring_detail_reference
  ).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:

  • (PaymentService::CancelOrRefundResponse) —

    The response object.



248
249
250
 
# File 'lib/adyen/api.rb', line 248

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:

  • (PaymentService::CancelResponse) —

    The response object.



262
263
264
 
# File 'lib/adyen/api.rb', line 262

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:

  • (PaymentService::CaptureResponse) —

    The response object.

See Also:



215
216
217
 
# File 'lib/adyen/api.rb', line 215

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:

  • (RecurringService::DisableResponse) —

    The response object.



284
285
286
287
288
289
 
# File 'lib/adyen/api.rb', line 284

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:

  • (RecurringService::ListResponse) —

    The response object.



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

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:

  • (PaymentService::RefundResponse) —

    The response object.



233
234
235
 
# File 'lib/adyen/api.rb', line 233

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:

  • (RecurringService::StoreTokenResponse) —

    The response object



346
347
348
349
350
351
352
 
# File 'lib/adyen/api.rb', line 346

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