Server-Side Implementation

RubySDK

• Current Braintree Languages
• Java
• .NET
• Node.js
• PHP
• Python
• Ruby

This page describes the server-side steps for processing Apple Pay transactions, verifying and vaulting Apple Pay cards, and handling Apple Pay card verification using the Braintree SDK.

Create a transaction

Like all Braintree SDK integrations, you will receive a payment method nonce when your user successfully authorizes payment. Pass this nonce to your server, and create a transaction.

Collect device data from the client and include it in device_data_from_the_client in the transaction.

result = gateway.transaction.sale(
    :amount => "10.00",
    :payment_method_nonce => nonce_from_the_client,
    :device_data => device_data_from_the_client,
    :options => {
        :submit_for_settlement => true
    },
    :billing => {
        :postal_code => postal_code_from_the_client
    }
);

If you've already integrated Braintree SDKs to handle payment method nonces for other payment methods, reuse your existing implementation. The preceding example works with a payment method nonce that is associated with any new payment methods that you choose to accept in the future.

For information about enabling verification for cards in Apple Pay transactions, see Enabling Apple Pay card verification.

For certain account setups, PayPal recommends that merchants collect and pass billing address information when they store payment methods or create transactions. Passing the billing address details (minimally, the postal code) helps prevent authorization failures. To learn more about recommendations for your specific account setup, contact us.

Vault Apple Pay cards

Apple Pay cards can only be saved to your Vault for specific use cases. For more information, see this support article.

If your use case is supported, you can store a customer's Apple Pay card in your Vault in a few different ways:

• In a separate Payment Method: Create request
• In a separate Customer: Create or Customer: Update request
• In your Transaction: Sale request by using options.store_in_vault or options.store_in_vault_on_success

Enable Apple Pay card verification

There are 2 ways to enable $0 authorization verifications for Apple Pay:

• Verifying all Apple Pay cards by default: Braintree strongly recommends this option, which uses a toggle in the Control Panel to set the default behavior, so that you verify all Apple Pay cards before you store them in your Vault.
• Making a one-time verification request: Alternatively, you can use a one-time request for verification with specific APIs.

Verify all Apple Pay cards by default

To verify all Apple Pay cards before vaulting by default:

1. Log into the Control Panel.
2. Select the gear icon in the top-right corner.
3. Select Processing from the drop-down menu.
4. Scroll to the Vaulting section.
5. Next to Apple Pay Card Verification, select the toggle to enable it.

When the toggle is enabled, the gateway verifies that Apple Pay cards are valid. It does not store invalid cards in the Vault. For information about the way that this default setting interacts with one-time verification requests, see Verification behavior.

Run a one-time verification request

If you don't want to verify all Apple Pay cards by default, you can run a one-time request that passes verify_card = true as a parameter on options.verify_card when you perform the following actions:

result = gateway.payment_method.create(
  customer_id: "11111111111",
  payment_method_nonce: "9fffffff-aaaa-4444-etce-therestoftheowl",
  options: {
    verify_card: true, # Takes precedence over Control Panel toggle
    verification_merchant_account_id: "a_MAID" # Optional, choose a non-default merchant account if desired
  }
)

result = gateway.customer.create(
  first_name: "Jane",
  last_name: "Wallets",
  payment_method_nonce: "9fffffff-aaaa-4444-etce-therestoftheowl",
  apple_pay_card: {
    options: {
      verify_card: true, # Takes precedence over Control Panel toggle
      verification_merchant_account_id: "a_MAID" # Optional, choose a non-default merchant account if desired
    }
  }
)

result = gateway.customer.update(
  last_name: "Wallets Sr.",
  payment_method_nonce: "fake-apple-pay-mastercard-nonce",
  apple_pay_card: {
    options: {
      verify_card: true, # Takes precedence over Control Panel toggle
    }
  }
)

To understand how one-time verification settings interact with default verification settings, see Verification behavior.

Verification behavior

An API parameter takes priority over the toggle in all cases. In other words, if you use the toggle in the Control Panel to activate Apple Pay Card Verification by default, and you also pass verify_card: false, no verification occurs. The following table describes how the verify_card parameter values and toggle settings affect verification behavior.

Receive verification results

The response objects for customer.create, customer.update, and payment_method.create contain a verification object. If verification fails, the gateway does not vault the card.

result = gateway.customer.create(
  first_name: "Jane",
  last_name: "Wallets",
  email: "wallets@example.com",
  payment_method_nonce: "9fffffff-aaaa-4444-etce-therestoftheowl",
  apple_pay_card: {
    options: {
      verify_card: true, # Takes precedence over Control Panel toggle
      verification_merchant_account_id: "a_MAID" # Optional, choose a non-default merchant account if desired
    }
  }
)

if result.success?
  # result.customer.payment_methods.first.verification
else
  # Verification failed, card not vaulted
end

result = gateway.payment_method.create(
  first_name: "Jane",
  last_name: "Wallets",
  email: "wallets@example.com",
  payment_method_nonce: "9fffffff-aaaa-4444-etce-therestoftheowl",
  options: {
    verify_card: true, # Takes precedence over Control Panel toggle
    verification_merchant_account_id: "a_MAID" # Optional, choose a non-default merchant account if desired
  }
)

if result.success?
  # result.payment_method.verification
else
  # Verification failed, card not vaulted
end

Create transactions on verified Apple Pay cards

When you create transactions on a vaulted Apple Pay card, submit them as merchant-initiated transactions by passing the appropriate merchant-initiated transaction_source flag in the transaction.sale call:

result = gateway.transaction.sale(
  amount: "3.50",
  payment_method_token: "apple-pay-pmt",
  transaction_source: "unscheduled" # recurring, unscheduled, or installment
)