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 = '[email protected]'
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

#authorise_one_click_payment(reference, amount, shopper, card, recurring_detail_reference, fraud_offset = nil, instant_capture = false) ⇒ 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

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.

  • 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

Options Hash (card):

  • :cvc (String) —

    The card’s verification code.

Returns:

See Also:



255
256
257
258
259
260
261
262
263
264
 
# File 'lib/adyen/api.rb', line 255

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

#authorise_payment(reference, amount, shopper, card, enable_recurring_contract = false, fraud_offset = nil, instant_capture = false) ⇒ 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

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:



155
156
157
158
159
160
161
162
163
164
 
# File 'lib/adyen/api.rb', line 155

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

#authorise_recurring_payment(reference, amount, shopper, recurring_detail_reference = 'LATEST', fraud_offset = nil, instant_capture = false) ⇒ 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

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:



203
204
205
206
207
208
209
210
211
 
# File 'lib/adyen/api.rb', line 203

def authorise_recurring_payment(reference, amount, shopper, recurring_detail_reference = 'LATEST', fraud_offset = nil, instant_capture = false)
  params = { :reference => reference,
             :amount    => amount,
             :shopper   => shopper,
             :recurring_detail_reference => recurring_detail_reference,
             :fraud_offset => fraud_offset,
             :instant_capture => instant_capture }
  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.

Parameters:

  • psp_reference (String) —

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

Returns:



318
319
320
 
# File 'lib/adyen/api.rb', line 318

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.

Parameters:

  • psp_reference (String) —

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

Returns:



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

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.

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:



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

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.

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:



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

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

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.

  • document_number (String) —

    Social Security

  • selected_brand (String) —

    Billet brand

  • shopper_name (Hash) —

    a customizable set of options

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

Returns:



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

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.

Parameters:

  • shopper_reference (String) —

    The ID used to store payment details for this shopper.

Returns:



342
343
344
 
# File 'lib/adyen/api.rb', line 342

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

#pay_instantly(reference, amount, shopper, card, enable_recurring_contract = false, fraud_offset = nil) ⇒ Object

Make an instant payment.

Technically - authorisation with immediate (no delay) capture.

See Also:



105
106
107
 
# File 'lib/adyen/api.rb', line 105

def pay_instantly(reference, amount, shopper, card, enable_recurring_contract = false, fraud_offset = nil)
  authorise_payment(reference, amount, shopper, card, enable_recurring_contract, fraud_offset, true)
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.

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:



303
304
305
 
# File 'lib/adyen/api.rb', line 303

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:

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:



416
417
418
419
420
421
422
 
# File 'lib/adyen/api.rb', line 416

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