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.

Defined Under Namespace

Classes: PaymentService, RecurringService, Response, SimpleSOAPClient, XMLQuerier

Instance Method Summary collapse

Instance Method Details

#authorise_one_click_payment(reference, amount, shopper, card, recurring_detail_reference, fraud_offset = nil) ⇒ PaymentService::AuthorisationResponse

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' },
  { :cvc => '737' }
  detail
)
payment.authorised? # => true

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):

  • :cvc (String)

    The card’s verification code.

See Also:

  • capture_payment
  • list_recurring_details


246
247
248
249
250
251
252
253
254
# File 'lib/adyen/api.rb', line 246

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

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

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

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.

See Also:

  • capture_payment


148
149
150
151
152
153
154
155
156
# File 'lib/adyen/api.rb', line 148

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

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

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

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

See Also:

  • capture_payment
  • list_recurring_details


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

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

#cancel_or_refund_payment(psp_reference) ⇒ PaymentService::CancelOrRefundResponse

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.



308
309
310
# File 'lib/adyen/api.rb', line 308

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

#cancel_payment(psp_reference) ⇒ PaymentService::CancelResponse

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.



322
323
324
# File 'lib/adyen/api.rb', line 322

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

#capture_payment(psp_reference, amount) ⇒ PaymentService::CaptureResponse

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.

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.

See Also:



275
276
277
# File 'lib/adyen/api.rb', line 275

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

#disable_recurring_contract(shopper_reference, recurring_detail_reference = nil) ⇒ RecurringService::DisableResponse

Disable the recurring contract details for a shopper.



344
345
346
347
348
349
# File 'lib/adyen/api.rb', line 344

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

#generate_billet(reference, amount, shopper_name, social_security_number, selected_brand, delivery_date) ⇒ PaymentService::BilletResponse

Generate a Billet - *Brazian users only*

Billet (Boleto Bancário), often simply referred to as Boleto, is an offline payment method used in Brazil . The consumer will take the Boleto form to an ATM, bank, an approved facility, or access their online banking system to complete the payment. Once the Boleto is paid, the bank will send Adyen a file confirming that the payment was made, this usually takes one day, but it may occur up to 6 days after the payment. If a Boleto is not paid, the transaction will expire once the expirationDate is reached. For more information check the Adyen API Manual - 7 - Boleto Bancário(page 30)

number(CPF in Brazil)

Examples:

response = Adyen::API.generate_billet(
  invoice.id
  { currency: "BRL", value: (invoice.amount).to_i },
  { first_name: "Simon", last_name: "Hopper" },
  document_number,
  selected_brand
)
response.success? # => true

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_name):

  • :first_name (String)

    The shopper’s first name

  • :last_name (String)

    The shopper’s last name



92
93
94
95
96
97
98
99
100
# File 'lib/adyen/api.rb', line 92

def generate_billet(reference, amount, shopper_name, social_security_number, selected_brand, delivery_date)
  params = { :reference              => reference,
             :amount                 => amount,
             :shopper_name           => shopper_name,
             :social_security_number => social_security_number,
             :selected_brand         => selected_brand,
             :delivery_date          => delivery_date }
  PaymentService.new(params).generate_billet
end

#list_recurring_details(shopper_reference) ⇒ RecurringService::ListResponse

Retrieve the recurring contract details for a shopper.



332
333
334
# File 'lib/adyen/api.rb', line 332

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

#refund_payment(psp_reference, amount) ⇒ PaymentService::RefundResponse

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.

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.



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

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

#store_recurring_token(shopper, params) ⇒ RecurringService::StoreTokenResponse

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:

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).



406
407
408
409
410
411
412
# File 'lib/adyen/api.rb', line 406

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