Skip to main content

Card via Adyen

Accept credit and debit card payments through Adyen's secure payment processing platform. This integration supports all major card networks with advanced fraud protection and 3D Secure authentication.

Setup​

Please follow the common Adyen instructions to get set up with Adyen.

Features​

After setting up an Adyen account we recommend you configure the following things in the developer area so you can use all features. Go to Developers -> Additional data in the Adyen dashboard and then make sure the following fields are selected.

  • Recurring Details
  • Raw acquirer result
  • Payment account reference

Integration​

API Request​

curl --request POST \
  --url https://api.efundpay.com/v4/transactions \
  --header 'Authorization: Bearer <token>' \
  --header 'x-merchant-account-id: <x-merchant-account-id>' \
  --header 'Content-Type: application/json' \
  --data '{
    "amount": {
      "currency": "USD",
      "value": 2500
    },
    "payment_method": {
      "method": "adyen",
      "payment_method_data": {
        "type": "scheme",
        "encrypted_card_number": "test_4111111111111111",
        "encrypted_expiry_month": "test_03",
        "encrypted_expiry_year": "test_2030",
        "encrypted_security_code": "test_737"
      },
      "browser_info": {
        "accept_header": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8",
        "color_depth": 24,
        "language": "en-US",
        "java_enabled": false,
        "screen_height": 1080,
        "screen_width": 1920,
        "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"
      }
    },
    "external_identifier": "order-12345"
  }'

Payment Flow​

  1. Initialize Payment - Create payment request with EFundPay
  2. Client-Side Encryption - Encrypt card data using Adyen's JavaScript library
  3. Payment Processing - Adyen processes the payment
  4. 3D Secure - Handle 3D Secure authentication if required
  5. Webhook Notification - Receive payment status via webhook
  6. Final Result - Handle success/failure response

Configuration​

Required Parameters​

  • amount.currency - Three-letter ISO currency code
  • amount.value - Payment amount in smallest currency unit
  • payment_method_data.type - Set to "scheme" for card payments
  • encrypted_card_number - Encrypted card number
  • encrypted_expiry_month - Encrypted expiry month
  • encrypted_expiry_year - Encrypted expiry year
  • encrypted_security_code - Encrypted security code (CVV)

Optional Parameters​

  • browser_info - Browser information for fraud detection
  • billing_address - Customer billing address
  • shipping_address - Customer shipping address
  • merchant_order_id - Your internal order reference

Auto-Rescue​

Adyen's auto-rescue feature is supported by this connector. This feature will automatically retry customer-not-present card transactions when they are declined on the first request. To enable this feature, pass in the following connection options for Adyen when making a subsequent payment request.

POST /transactions

{
    "amount": 1299,
    "country": "US",
    "currency": "USD",
    "intent": "capture",
    "payment_method": {
        "method": "id",
        "id": "7f6fb9ca-eb1c-42c6-9b65-8f1c699b84bd"
    },
    "connection_options": {
        "adyen-card": {
            "autoRescue": true,
            "maxDaysToRescue": 5
        }
    },
    "payment_source": "card_on_file",
    "is_subsequent_payment": true,
    "merchant_initiated": true
}

Please note that this feature only works for customer-not-present transaction where is_subsequent_payment is set to true.

The following fields will need to be set.

  • autoRescue - A boolean value that enables the feature. This defaults to false.
  • maxDaysToRescue - The rescue window, in days. You can specify between 1 and 48 days. Adyen recommends using a rescue window of one calendar month (30 days).
  • autoRescueScenario - This is one of the test scenarios as defined by Adyen. This will only work in sandbox. Please be aware that the webhooks from Adyen in these test scenarios may take a few minutes to arrive.

We will mark a transaction as processing when a transaction has been accepted for automatic retries using this feature. When we receive a webhook for a successful payment or an eventual rejection, we will update the status accordingly.

For auto-rescue to work it's important to ensure Adyen has been setup to send webhooks in a JSON format.

Payouts / Original Credit Transactions​

Adyen Transfers API is supported by this connector to enable Payouts/Original Credit Transactions. This feature needs to be enabled in your Adyen account for it to work. You will also need to provide a balance account id in the configuration of your Adyen connection in the dashboard. Your payouts will be funded from this balance account.

Response Handling​

Success Response​

{
  "type": "transaction",
  "id": "txn_123456789",
  "status": "processing",
  "psp_reference": "8535296650153317",
  "result_code": "Authorised",
  "external_identifier": "order-12345"
}

Webhook Notification​

{
  "ll_transaction_id": "2022012601122644",
  "merchant_transaction_id": "order-12345",
  "payment_data": {
    "payment_status": "PS",
    "payment_amount": "25.00",
    "payment_currency_code": "USD",
    "payment_time": "20220126141430",
    "adyen_psp_reference": "8535296650153317",
    "result_code": "Authorised"
  }
}

Client-Side Integration​

Adyen Web Components​

// Load Adyen Web Components
const checkout = await AdyenCheckout({
  environment: 'test',
  clientKey: 'test_...',
  paymentMethodsResponse: paymentMethodsResponse,
  onSubmit: (state, component) => {
    // Handle payment submission
    makePayment(state.data);
  },
  onAdditionalDetails: (state, component) => {
    // Handle 3D Secure
    makeDetailsCall(state.data);
  }
});

// Mount the component
checkout.create('card').mount('#card-container');

Payment Submission​

async function makePayment(paymentData) {
  try {
    const response = await fetch('/api/payments', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify(paymentData),
    });
    
    const result = await response.json();
    handlePaymentResult(result);
  } catch (error) {
    console.error('Payment failed:', error);
  }
}

Testing​

Test Cards​

Adyen provides various test card numbers:

  • Success: 4212345678901247
  • Decline: 4212345678901254
  • 3D Secure: 4212345678901247
  • Insufficient Funds: 4212345678901254

Test Environment​

  • Use test API keys for development
  • Test with Adyen's test merchant account
  • Verify webhook notifications in test mode
  • Test 3D Secure flows

Security Considerations​

PCI Compliance​

  • Adyen handles PCI compliance for card data
  • Use Adyen's client-side encryption
  • Never store raw card data
  • Implement proper webhook signature verification

Fraud Prevention​

  • Enable Adyen's risk management tools
  • Implement 3D Secure authentication
  • Monitor for suspicious activity
  • Use Adyen's fraud detection features

Common Issues​

Payment Failures​

  • Card Declined - Check card details and funds
  • 3D Secure Required - Implement 3D Secure flow
  • Invalid Amount - Ensure amount is in correct format
  • Currency Mismatch - Verify currency settings

Integration Issues​

  • Webhook Not Received - Check webhook endpoint and signature
  • Encryption Errors - Verify client-side encryption setup
  • Invalid API Key - Verify API key configuration

Best Practices​

User Experience​

  • Implement proper loading states
  • Show clear error messages
  • Provide multiple payment options
  • Optimize for mobile devices

Technical Implementation​

  • Use webhooks for real-time updates
  • Implement proper error handling
  • Store payment references
  • Handle network failures gracefully

Security​

  • Always use HTTPS
  • Verify webhook signatures
  • Implement proper session management
  • Regular security audits

Support​

For technical support with Card via Adyen integration:

  • EFundPay Support - Contact our technical team
  • Adyen Support - Use Adyen's support resources
  • Adyen Documentation - Comprehensive API documentation
Powered by Docusaurus