Skip to main content

Apple Pay

Cards Bundle

Select your integration model below. If you haven't chosen yet, see the Overview for a comparison.

Your server decrypts the PKPaymentToken and sends the extracted card data to EBANX using the network_token_* fields. Use this model if you already have Apple Pay decryption in place.

Before you start

  • API authentication. All API requests must be authenticated using JWS (JSON Web Signature). The legacy integration_key is being deprecated — if you still use it, follow the Migration Guide to transition to JWS.
  • Active EBANX Direct integration. You need an existing EBANX Direct API integration.
  • Apple Developer Program membership. With a registered Merchant ID and your own Payment Processing Certificate.
  • Server-side Apple Pay decryption. Your backend must implement ECDH-ES decryption for EC_v1 tokens.

  1. Select your environment
    ​

    Select the appropriate environment for your integration. Use the sandbox environment for testing, or the production environment for live transactions. Use the URL for your HTTP requests based on your selection.

    Check the method's availability for your country and tenant in Payment Methods by Country. Questions about tenant and environment? Check our API Operability and API Endpoints.

    Cross-border sandbox
    https://sandbox.ebanxpay.com/ws/direct

  2. Decrypt the PKPaymentToken
    ​

    After the customer authenticates, decrypt the PKPaymentToken on your server to extract:

    • DPAN (applicationPrimaryAccountNumber). The network token that replaces the card PAN. For recurring or merchant-initiated transactions, Apple may return an MPAN in this field instead — a merchant-scoped token that persists across devices and enables MIT flows.
    • Expiry date (applicationExpirationDate). In YYMMDD format; convert to MM/YYYY.
    • Cryptogram (paymentData.onlinePaymentCryptogram). One-time auth value.
    • ECI (paymentData.eciIndicator). Electronic commerce indicator.

  3. Prepare your request
    ​

    Add the following parameters to the creditcard object in your /ws/direct request.


    ParameterTypeDescription
    network_token_panstringRequired. DPAN or MPAN from applicationPrimaryAccountNumber. Use MPAN for recurring and merchant-initiated transactions.
    network_token_expire_datestringRequired. Token expiry in MM/YYYY format, converted from Apple Pay's YYMMDD field.
    network_token_cryptogramstringRequired for CIT. onlinePaymentCryptogram from the decrypted token. Base64-encoded. Omit for MIT flows using an MPAN.
    network_token_wallet_typestringRequired. Must be "apple".
    network_token_ecistringRecommended. eciIndicator from the decrypted token (e.g. "05", "07"). Enables liability shift when the issuer supports it.
    card_namestringRequired. Cardholder name. Use cardholderName from the token when available.

  4. Sample request
    ​

    Country-specific fields

    Always include country (two-letter code, e.g. "br", "ar", "cl") and the matching currency_code (e.g. "BRL", "ARS", "CLP"). The document field is required in most markets and its format varies by country — for example, CPF or CNPJ in Brazil, CUIT/CUIL in Argentina, and RUT in Chile. See Payment Fields by Country for the full reference.

    The example below shows a Brazil transaction. Adjust country, currency_code, and document for the target market.

    Shell
    curl -X POST \
      --location 'https://sandbox.ebanxpay.com/ws/direct' \
      --header 'Content-Type: application/json' \
      --header 'X-JWS-Signature: {{jws_signature}}' \
      --data '{
        "payment": {
          "merchant_payment_code": "{{unique_merchant_code}}",
          "amount_total": 99.85,
          "currency_code": "BRL",
          "name": "John Doe",
          "email": "john.doe@example.com",
          "document": "{{cpf_or_cnpj}}",
          "address": "123 Main Street",
          "street_number": "100",
          "city": "São Paulo",
          "state": "SP",
          "zipcode": "01310100",
          "country": "br",
          "phone_number": "5511999990000",
          "payment_type_code": "visa",
          "creditcard": {
            "card_name": "John Doe",
            "network_token_pan": "{{dpan}}",
            "network_token_expire_date": "12/2027",
            "network_token_cryptogram": "{{base64Cryptogram}}",
            "network_token_eci": "05",
            "network_token_wallet_type": "apple"
          }
        }
      }'

  5. Sample response
    ​

    A successful request returns a response similar to the example below.

    JSON
    {
      "payment": {
        "hash": "{{payment_hash}}",
        "country": "br",
        "merchant_payment_code": "{{unique_merchant_code}}",
        "status": "CO",
        "status_date": "{{YYYY-MM-DD HH:mm:ss}}",
        "open_date": "{{YYYY-MM-DD HH:mm:ss}}",
        "confirm_date": "{{YYYY-MM-DD HH:mm:ss}}",
        "amount_br": "99.85",
        "amount_ext": "99.85",
        "currency_ext": "BRL",
        "payment_type_code": "visa",
        "transaction_status": {
          "acquirer": "EBANX",
          "code": "OK",
          "description": "Accepted",
          "authcode": "{{authcode}}"
        },
        "pre_approved": true,
        "capture_available": false
      },
      "status": "SUCCESS"
    }

  6. Congratulations!
    ​

    Apple Pay (Model 1) is live.


Resources​

Use the following resources when testing in your sandbox environment.

Credit Card Icon

Sample Cards

Click here to view mock card data to validate your payment integration.

Click to explorechevron_right
Globe Icon

API Reference

Click here to access detailed API documentation to integrate efficiently.

Click to explorechevron_right
Mock Data Icon

Mock Customer Data

Click here to view mock customer data for testing and validating user flows.

Click to explorechevron_right
Warning Icon

Error Codes

Click here to review common error codes to troubleshoot and resolve issues quickly.

Click to explorechevron_right

Still need help?

Help Image

We hope this article was helpful. If you still have questions, you can explore the following options: