🍎📱 Apple Pay & Google Pay — Wallet Charge (Decrypted Payload)

Create a charge with Apple Pay or Google Pay when the wallet payload has already been decrypted on your backend.

Use this flow when your platform handles device-side wallet decryption and you want to submit the final card data (PAN/DPAN, expiry, CVV) together with wallet authentication fields (ECI/CAVV) directly to A55.

⚠️
Important Notice
This integration requires specific configuration and gateway support. Please contact A55 support to verify availability and enable Apple Pay/Google Pay processing for your account before implementation.

🔄 Payment Flow Diagram

sequenceDiagram
    autonumber
    participant Customer as 👤 Customer
    participant Wallet as 🍎📱 Apple/Google Pay
    participant Merchant as 🏪 Merchant Backend
    participant A55 as 💳 A55 API
    participant Gateway as 🏦 Payment Gateway

    rect rgba(65, 105, 225, 0.2)
        Note over Customer,Merchant: Step 1: Wallet Selection & Authentication
        Customer->>Wallet: Selects Apple Pay / Google Pay
        Wallet->>Customer: Authenticates (FaceID/Fingerprint)
        Wallet-->>Merchant: Returns encrypted payment token
        Note right of Merchant: Token contains: DPAN, expiry, cryptogram
    end

    rect rgba(255, 165, 0, 0.2)
        Note over Merchant: Step 2: Token Decryption
        Merchant->>Merchant: Decrypts wallet payload
        Note right of Merchant: Extracts: PAN/DPAN, expiry, CVV, ECI, CAVV
    end

    rect rgba(34, 139, 34, 0.2)
        Note over Merchant,Gateway: Step 3: Payment Authorization
        Merchant->>A55: POST /bank/wallet/charge/<br/>(card data + wallet auth)
        activate A55
        A55->>Gateway: Authorizes transaction
        activate Gateway
        Gateway-->>A55: Authorization result
        deactivate Gateway
        A55-->>Merchant: Returns charge status
        deactivate A55
    end

    rect rgba(220, 20, 60, 0.2)
        Note over A55,Merchant: Step 4: Final Notification
        A55-->>Merchant: Sends webhook with final status
        Note right of Merchant: Webhook confirms payment result
    end

🎯 When to Use This Integration

This integration is recommended when:

✅ You control the Apple Pay / Google Pay token decryption
✅ You already extracted DPAN/PAN, expiration date, CVV
✅ You want to forward wallet authentication values (eci, cavv) to A55
✅ You do not want A55 to handle raw wallet token decryption

📋 Required Fields

Mandatory Parameters

Field	Type	Description	Example
`type_charge`	string	Payment method type	`applepay` or `googlepay`
`wallet_uuid`	string	Wallet identifier	`00000000-0000-0000-0000-000000000000`
`merchant_id`	string	Merchant identifier	`11111111-1111-1111-1111-111111111111`
`payer_name`	string	Customer's full name	`Jane Doe`
`payer_email`	string	Customer's email	`[email protected]`
`currency`	string	Transaction currency	`BRL`.
`installment_value`	float	Payment amount	`100.00`
`description`	string	Payment description	`Order #12345`
`items`	array	List of purchased items	See items structure below

Card Data (Decrypted from Wallet)

Field	Type	Description	Example
`card_number`	string	Card PAN or DPAN	`5200828282828210`
`card_expiry_month`	string	Expiration month (MM)	`12`
`card_expiry_year`	string	Expiration year (YYYY)	`2028`
`card_cvv`	string	Card security code	`123`

Wallet Authentication (applepay / googlepay object)

Field	Type	Description	Example
`eci`	string	Electronic Commerce Indicator	`05`, `07`
`cavv`	string	Cardholder Authentication Value	`AAABBBCCC123456789`
`type`	string	Card type	`credit_card` or `debit_card`

⚡
Important: eci and cavv are mandatory for wallet transactions. These values are provided by Apple Pay/Google Pay and must be forwarded to ensure proper authentication.

Items Structure

Field	Type	Required	Description
`name`	string	Yes	Item name
`description`	string	No	Item description
`quantity`	integer	Yes	Quantity
`total_amount`	float	Yes	Total amount (unit × quantity)
`unit_amount`	float	Yes	Unit price
`sku`	string	No	Stock Keeping Unit
`code`	string	No	Internal product code

🔐 Strongly Recommended Fields

Field	Type	Description	Why It Matters
`payer_address`	object	Customer billing address	Fraud prevention
`shipping_address`	object	Delivery address	Fraud prevention
`device_info`	object	Device information	anti-fraud
`webhook_url`	string	URL for status notifications	Real-time updates

📤 Request Examples

Apple Pay (Decrypted Payload)

{
  "wallet_uuid": "00000000-0000-0000-0000-000000000000",
  "merchant_id": "11111111-1111-1111-1111-111111111111",
  "payer_name": "Jane Doe",
  "payer_email": "[email protected]",
  "currency": "BRL",
  "installment_value": 100.00,
  "installment_count": 1,
  "due_date": "2025-12-31",
  "description": "Order #12345",
  "items": [
    {
      "name": "Premium Headphones",
      "img": "https://example.com/item.png",
      "description": "Wireless noise-canceling headphones",
      "quantity": 1,
      "total_amount": 100.00,
      "unit_amount": 100.00,
      "sku": "SKU-HEADPHONES-001",
      "code": "PROD-123"
    }
  ],
  "type_charge": "applepay",
  "card_number": "5200828282828210",
  "card_expiry_month": "12",
  "card_expiry_year": "2028",
  "card_cvv": "123",
  "applepay": {
    "eci": "05",
    "cavv": "AAABBBCCC123456789==",
    "type": "credit_card"
  },
  "device_info": {
    "ip_address": "177.10.10.10",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36"
  },
  "webhook_url": "https://merchant.example.com/webhook",
  "redirect_url": "https://merchant.example.com/return"
}

Google Pay (Decrypted Payload)

{
  "wallet_uuid": "00000000-0000-0000-0000-000000000000",
  "merchant_id": "11111111-1111-1111-1111-111111111111",
  "payer_name": "John Smith",
  "payer_email": "[email protected]",
  "payer_address": {
    "street": "Rua das Flores",
    "address_number": "456",
    "complement": "Suite 5",
    "neighborhood": "Jardins",
    "city": "São Paulo",
    "state": "SP",
    "postal_code": "01400-000",
    "country": "BR"
  },
  "currency": "BRL",
  "installment_value": 50.00,
  "installment_count": 2,
  "due_date": "2025-12-31",
  "description": "Subscription payment - Month 1",
  "items": [
    {
      "name": "Premium Plan",
      "description": "Monthly subscription",
      "quantity": 1,
      "total_amount": 100.00,
      "unit_amount": 100.00,
      "sku": "PLAN-PREMIUM",
      "code": "SUBS-001"
    }
  ],
  "type_charge": "googlepay",
  "card_number": "4111111111111111",
  "card_expiry_month": "07",
  "card_expiry_year": "2029",
  "card_cvv": "999",
  "googlepay": {
    "eci": "05",
    "cavv": "ZYX987654321ABCDEF==",
    "type": "credit_card"
  },
  "device_info": {
    "ip_address": "200.200.200.200",
    "user_agent": "Mozilla/5.0 (Linux; Android 14) AppleWebKit/537.36"
  },
  "webhook_url": "https://merchant.example.com/webhook",
  "redirect_url": "https://merchant.example.com/return"
}

📥 Response Example

Successful Authorization

{
  "charge_uuid": "22222222-2222-2222-2222-222222222222",
  "local_currency": 100.0,
  "currency": "BRL",
  "usd_currency": 18.50,
  "eur_currency": 16.20,
  "type": "applepay",
  "date": "2025-12-19",
  "description": "Order #12345",
  "status": "confirmed",
  "message": null,
  "installment_count": 1,
  "installments": [
    {
      "local_currency": 100.0,
      "currency": "BRL",
      "usd_currency": 18.50,
      "eur_currency": 16.20,
      "due_date": "2025-12-31",
      "status": "confirmed",
      "installment_number": 1
    }
  ],
}

🔔 Webhook Notification

After payment processing, A55 will send a POST request to your webhook_url:

{
  "charge_uuid": "22222222-2222-2222-2222-222222222222",
  "status": "confirmed",
  "transaction_reference": "your-reference-id"
}

Possible Status Values

Status	Description
`confirmed`	Payment successfully authorized
`paid`	Payment confirmed by gateway
`error`	Transaction failed

✅ Best Practices

Security

✅ Never log or store full card numbers (PAN/DPAN) in plain text
✅ Always forward eci and cavv from the wallet token
✅ Use HTTPS for all webhook endpoints
✅ Validate webhook signatures (if supported by your gateway)
✅ Implement idempotency keys to prevent duplicate charges

Integration

✅ Provide full address and device info to maximize approval rates
✅ Use webhook_url as the source of truth for payment status
✅ Test with sandbox credentials before going live

Error Handling

✅ Implement retry logic with exponential backoff for network errors
✅ Handle timeout scenarios appropriately
✅ Log all API responses for debugging and reconciliation
✅ Provide clear error messages to customers

📝 Additional Notes

Apple Pay Specific

Apple Pay tokens are ephemeral and expire quickly
You must decrypt the token immediately upon receipt
The eci value typically ranges from 05 to 07 for Apple Pay

Google Pay Specific

Google Pay supports both PAN (direct card) and DPAN (tokenized)
Ensure your Google Pay merchant configuration is active
The eci value is typically 05 for Google Pay 3DS transactions

Network Token Considerations

Wallet authentication values (eci, cavv) are mandatory for DPAN transactions
These values prove that the wallet provider authenticated the cardholder
Missing or incorrect values will result in transaction decline

🆘 Support

For questions about this integration:

📧 Email: [email protected]
📚 Full API documentation: https://docs.a55.tech
💬 Contact your account manager for enablement and configuration

Remember: Always verify that Apple Pay/Google Pay is enabled for your account before implementing this integration.

🍎📱 Apple Pay & Google Pay — Wallet Charge (Decrypted Payload)

Important Notice

🔄 Payment Flow Diagram

🎯 When to Use This Integration

📋 Required Fields

Mandatory Parameters

Card Data (Decrypted from Wallet)

Wallet Authentication (applepay / googlepay object)

Important: eci and cavv are mandatory for wallet transactions. These values are provided by Apple Pay/Google Pay and must be forwarded to ensure proper authentication.

Items Structure

🔐 Strongly Recommended Fields

📤 Request Examples

Apple Pay (Decrypted Payload)

Google Pay (Decrypted Payload)

📥 Response Example

Successful Authorization

🔔 Webhook Notification

Possible Status Values

✅ Best Practices

Security

Integration

Error Handling

📝 Additional Notes

Apple Pay Specific

Google Pay Specific

Network Token Considerations

🆘 Support

Important: `eci` and `cavv` are mandatory for wallet transactions. These values are provided by Apple Pay/Google Pay and must be forwarded to ensure proper authentication.