> This is Payabli documentation. For a complete page index, fetch https://docs.payabli.com/llms.txt — append .md to any page URL for lightweight markdown. For section-level indexes, query parameters, and other AI-optimized access methods, see https://docs.payabli.com/ai-agents.md

# Activate Apple Pay (API)

> Learn about setting up Apple Pay via the Payabli API

Payabli has simplified the process of getting ready to accept Apple Pay. You don't need to create your own Apple developer account, encryption keys, certificates, or merchant identifiers.

This guide walks through how to enable Apple Pay for your organization via the API.

Enabling Apple Pay via the API has several steps.

1. Add the domain.
2. Validate domain ownership.
3. Cascade the domain.
4. Activate the Apple Pay service for your org.

The following sections go over each step in detail.

## Add payment method domains

Payment method domains are the web domains where you can accept Apple Pay payments. Payabli needs to know which payment domains should accept Apple Pay payments to mitigate risk and make sure that transactions are coming from known websites. Managing your payment method domains involves configuring them in Payabli, and then verifying domain ownership with Apple.

To add a domain via the API, make a POST request to the [/PaymentMethodDomain](/developers/api-reference/paymentmethoddomain/paymentmethoddomain-add) endpoint.

### Request

POST [https://api-sandbox.payabli.com/api/PaymentMethodDomain](https://api-sandbox.payabli.com/api/PaymentMethodDomain)

```curl
curl -X POST https://api-sandbox.payabli.com/api/PaymentMethodDomain \
     -H "requestToken: <apiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "applePay": {
    "isEnabled": true
  },
  "googlePay": {
    "isEnabled": true
  },
  "domainName": "checkout.example.com",
  "entityId": 109,
  "entityType": "paypoint"
}'
```

```typescript
import { PayabliClient } from "@payabli/sdk-node";

async function main() {
    const client = new PayabliClient({
        apiKey: "YOUR_API_KEY_HERE",
    });
    await client.paymentMethodDomain.addPaymentMethodDomain({
        applePay: {
            isEnabled: true,
        },
        googlePay: {
            isEnabled: true,
        },
        domainName: "checkout.example.com",
        entityId: 109,
        entityType: "paypoint",
    });
}
main();

```

```python
from payabli import payabli, AddPaymentMethodDomainRequestApplePay, AddPaymentMethodDomainRequestGooglePay

client = payabli(
    api_key="YOUR_API_KEY_HERE",
)

client.payment_method_domain.add_payment_method_domain(
    apple_pay=AddPaymentMethodDomainRequestApplePay(
        is_enabled=True,
    ),
    google_pay=AddPaymentMethodDomainRequestGooglePay(
        is_enabled=True,
    ),
    domain_name="checkout.example.com",
    entity_id=109,
    entity_type="paypoint",
)

```

```java
package com.example.usage;

import io.github.payabli.api.PayabliPayabliApiOasClient;
import io.github.payabli.api.resources.paymentmethoddomain.requests.AddPaymentMethodDomainRequest;
import io.github.payabli.api.types.AddPaymentMethodDomainRequestApplePay;
import io.github.payabli.api.types.AddPaymentMethodDomainRequestGooglePay;

public class Example {
    public static void main(String[] args) {
        PayabliPayabliApiOasClient client = PayabliPayabliApiOasClient
            .builder()
            .apiKey("YOUR_API_KEY_HERE")
            .build();

        client.paymentMethodDomain().addPaymentMethodDomain(
            AddPaymentMethodDomainRequest
                .builder()
                .applePay(
                    AddPaymentMethodDomainRequestApplePay
                        .builder()
                        .isEnabled(true)
                        .build()
                )
                .googlePay(
                    AddPaymentMethodDomainRequestGooglePay
                        .builder()
                        .isEnabled(true)
                        .build()
                )
                .domainName("checkout.example.com")
                .entityId(109L)
                .entityType("paypoint")
                .build()
        );
    }
}
```

```ruby
require "payabli"

client = Payabli::Client.new(api_key: "YOUR_API_KEY_HERE")

client.payment_method_domain.add_payment_method_domain(
  apple_pay: {
    is_enabled: true
  },
  google_pay: {
    is_enabled: true
  },
  domain_name: "checkout.example.com",
  entity_id: 109,
  entity_type: "paypoint"
)

```

```csharp
using PayabliPayabliApiOas;
using System.Threading.Tasks;

namespace Usage;

public class Example
{
    public async Task Do() {
        var client = new PayabliPayabliApiOasClient(
            apiKey: "YOUR_API_KEY_HERE"
        );

        await client.PaymentMethodDomain.AddPaymentMethodDomainAsync(
            new AddPaymentMethodDomainRequest {
                ApplePay = new AddPaymentMethodDomainRequestApplePay {
                    IsEnabled = true
                },
                GooglePay = new AddPaymentMethodDomainRequestGooglePay {
                    IsEnabled = true
                },
                DomainName = "checkout.example.com",
                EntityId = 109L,
                EntityType = "paypoint"
            }
        );
    }

}

```

```go
package example

import (
    context "context"

    payabli "github.com/payabli/sdk-go"
    client "github.com/payabli/sdk-go/client"
    option "github.com/payabli/sdk-go/option"
)

func do() {
    client := client.NewClient(
        option.WithApiKey(
            "YOUR_API_KEY_HERE",
        ),
    )
    request := &payabli.AddPaymentMethodDomainRequest{
        ApplePay: &payabli.AddPaymentMethodDomainRequestApplePay{
            IsEnabled: payabli.Bool(
                true,
            ),
        },
        GooglePay: &payabli.AddPaymentMethodDomainRequestGooglePay{
            IsEnabled: payabli.Bool(
                true,
            ),
        },
        DomainName: payabli.String(
            "checkout.example.com",
        ),
        EntityId: payabli.Int64(
            int64(109),
        ),
        EntityType: payabli.String(
            "paypoint",
        ),
    }
    client.PaymentMethodDomain.AddPaymentMethodDomain(
        context.TODO(),
        request,
    )
}

```

```php
<?php

namespace Example;

use Payabli\PayabliClient;
use Payabli\PaymentMethodDomain\Requests\AddPaymentMethodDomainRequest;
use Payabli\Types\AddPaymentMethodDomainRequestApplePay;
use Payabli\Types\AddPaymentMethodDomainRequestGooglePay;

$client = new PayabliClient(
    apiKey: 'YOUR_API_KEY_HERE',
);
$client->paymentMethodDomain->addPaymentMethodDomain(
    new AddPaymentMethodDomainRequest([
        'applePay' => new AddPaymentMethodDomainRequestApplePay([
            'isEnabled' => true,
        ]),
        'googlePay' => new AddPaymentMethodDomainRequestGooglePay([
            'isEnabled' => true,
        ]),
        'domainName' => 'checkout.example.com',
        'entityId' => 109,
        'entityType' => 'paypoint',
    ]),
);

```

```swift
import Foundation

let headers = [
  "requestToken": "<apiKey>",
  "Content-Type": "application/json"
]
let parameters = [
  "applePay": ["isEnabled": true],
  "googlePay": ["isEnabled": true],
  "domainName": "checkout.example.com",
  "entityId": 109,
  "entityType": "paypoint"
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api-sandbox.payabli.com/api/PaymentMethodDomain")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

The domain must be public. It can't be `localhost`, hidden by a VPN, or protected by a password.

### Payment method domain examples

The following example walks through the general structure of payment method domains.

Pretend that you own the domain *example.com*, and you want to accept Apple Pay on a number of different pages on your various subdomains. You must set up payment method domains for each of your target domains and subdomains.

| Page URL                                                                                     | Payment Method Domain                     |
| -------------------------------------------------------------------------------------------- | ----------------------------------------- |
| [https://www.example.com/monthlydues](https://www.example.com/monthlydues)                   | [www.example.com](http://www.example.com) |
| [https://subdomain1.example.com/payments](https://subdomain1.example.com/payments)           | subdomain1.example.com                    |
| [https://subdomain2.example.com/donations/pay](https://subdomain2.example.com/donations/pay) | subdomain2.example.com                    |
| [https://subdomain3.example.com/order](https://subdomain3.example.com/order)                 | subdomain3.example.com                    |

## Verify domain ownership

Before you can accept Apple Pay, you must verify your ownership of a payment method domain using something called a domain-verification file. This process has two main steps: get the file, and host the file on your domain.

You must download the domain-verification file from these links. Choose the correct file for your Payabli environment.

* Sandbox: [Download](https://payabli-public-objects-sandbox.s3.amazonaws.com/apple-developer-merchantid-domain-association)
* Production [Download](https://payabli-public-objects-prod.s3.amazonaws.com/apple-developer-merchantid-domain-association)

After you've downloaded your domain-verification file, you need to host it on the path `/.well-known/apple-developer-merchantid-domain-association` for each the domains you want to use to accept Apple Pay.

For example:

* [https://www.example.com/.well-known/apple-developer-merchantid-domain-association](https://www.example.com/.well-known/apple-developer-merchantid-domain-association)
* [https://subdomain1.example.com/.well-known/apple-developer-merchantid-domain-association](https://subdomain1.example.com/.well-known/apple-developer-merchantid-domain-association)
* [https://subdomain2.example.com/.well-known/apple-developer-merchantid-domain-association](https://subdomain2.example.com/.well-known/apple-developer-merchantid-domain-association)
* [https://subdomain3.example.com/.well-known/apple-developer-merchantid-domain-association](https://subdomain3.example.com/.well-known/apple-developer-merchantid-domain-association)

Payabli automatically checks for the domain-verification file. If verification succeeds, the domain is activated in Payabli. If verification fails, the domain is added but remains inactive. You can verify the domain later.

## Cascade domains

You have the option to cascade domains. When you cascade a domain, all of the organization's children, including suborganizations and paypoints, inherit the domain. This reduces future operational overhead by automatically adding verified domains to all new suborganizations and paypoints. Payabli strongly recommends cascading domains.

Cascade a domain via the API by sending a POST request to [/PaymentMethodDomain/\{domainId}/cascade](/developers/api-reference/paymentmethoddomain/paymentmethoddomain-cascade).

### Request

POST [https://api-sandbox.payabli.com/api/PaymentMethodDomain/\{domainId}/cascade](https://api-sandbox.payabli.com/api/PaymentMethodDomain/\{domainId}/cascade)

```curl
curl -X POST https://api-sandbox.payabli.com/api/PaymentMethodDomain/pmd_b8237fa45c964d8a9ef27160cd42b8c5/cascade \
     -H "requestToken: <apiKey>"
```

```typescript
import { PayabliClient } from "@payabli/sdk-node";

async function main() {
    const client = new PayabliClient({
        apiKey: "YOUR_API_KEY_HERE",
    });
    await client.paymentMethodDomain.cascadePaymentMethodDomain("pmd_b8237fa45c964d8a9ef27160cd42b8c5");
}
main();

```

```python
from payabli import payabli

client = payabli(
    api_key="YOUR_API_KEY_HERE",
)

client.payment_method_domain.cascade_payment_method_domain(
    domain_id="pmd_b8237fa45c964d8a9ef27160cd42b8c5",
)

```

```java
package com.example.usage;

import io.github.payabli.api.PayabliPayabliApiOasClient;

public class Example {
    public static void main(String[] args) {
        PayabliPayabliApiOasClient client = PayabliPayabliApiOasClient
            .builder()
            .apiKey("YOUR_API_KEY_HERE")
            .build();

        client.paymentMethodDomain().cascadePaymentMethodDomain("pmd_b8237fa45c964d8a9ef27160cd42b8c5");
    }
}
```

```ruby
require "payabli"

client = Payabli::Client.new(api_key: "YOUR_API_KEY_HERE")

client.payment_method_domain.cascade_payment_method_domain(domain_id: "pmd_b8237fa45c964d8a9ef27160cd42b8c5")

```

```csharp
using PayabliPayabliApiOas;
using System.Threading.Tasks;

namespace Usage;

public class Example
{
    public async Task Do() {
        var client = new PayabliPayabliApiOasClient(
            apiKey: "YOUR_API_KEY_HERE"
        );

        await client.PaymentMethodDomain.CascadePaymentMethodDomainAsync(
            "pmd_b8237fa45c964d8a9ef27160cd42b8c5"
        );
    }

}

```

```go
package example

import (
    context "context"

    client "github.com/payabli/sdk-go/client"
    option "github.com/payabli/sdk-go/option"
)

func do() {
    client := client.NewClient(
        option.WithApiKey(
            "YOUR_API_KEY_HERE",
        ),
    )
    client.PaymentMethodDomain.CascadePaymentMethodDomain(
        context.TODO(),
        "pmd_b8237fa45c964d8a9ef27160cd42b8c5",
    )
}

```

```php
<?php

namespace Example;

use Payabli\PayabliClient;

$client = new PayabliClient(
    apiKey: 'YOUR_API_KEY_HERE',
);
$client->paymentMethodDomain->cascadePaymentMethodDomain(
    'pmd_b8237fa45c964d8a9ef27160cd42b8c5',
);

```

```swift
import Foundation

let headers = ["requestToken": "<apiKey>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://api-sandbox.payabli.com/api/PaymentMethodDomain/pmd_b8237fa45c964d8a9ef27160cd42b8c5/cascade")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

You can run a GET request to [/PaymentMethodDomain/\{domainId}](/developers/api-reference/paymentmethoddomain/paymentmethoddomain-get) to check the cascade status.

The `cascades.jobStatus` field indicates whether the cascade process is complete, failed, or in progress.

```json {5}
 // response truncated 
    "cascades": [
      {
        "jobId": "550139",
        "jobStatus": "completed",
        "jobErrorMessage": null,
        "createdAt": "2024-09-05T14:13:54.698Z",
        "updatedAt": "2024-09-05T14:13:54.698Z"
      }
    ],
```

Payabli recommends a 10 second polling interval when checking domain cascade status.

## Activate Apple Pay

To activate Apple Pay for an organization, make a POST request to the [/Wallet/applepay/configure-organization](/developers/api-reference/wallet/applepay/applepay-configure-organization).

In the body, send `isEnabled` as `true` to activate the Apple Pay for the organization. Send `cascade` as `true` to activate Apple Pay for the organization's children (including suborganizations and paypoints).

```bash Example activation request
  curl -X POST https://api-sandbox.payabli.com/api/Wallet/applepay/configure-organization \
    -H 'Content-Type: application/json' \
    -H 'requestToken: <API TOKEN>' \
    -d '{
        "orgId": 123,
        "isEnabled": true,
        "cascade": true
    }'
```

After you've sent the activation request, Payabli will enable the service and cascade the settings, if applicable. This can take a few minutes, depending on how your entities are structured.

To check whether Apple Pay is activated, send a GET request to [/api/Organization/settings/\{orgId}](/developers/api-reference/organization/get-organization-settings). Check the response for `forWallets`, when Apple Pay is active, you'll see the following in the response:

```json
 "forWallets": [
    {
      "key": "IsApplePayEnabled",
      "value": "true",
      "readOnly": true
    }
  ]
```

## Related resources

See these related resources to help you get the most out of Payabli.

* **[Apple Pay overview](/guides/pay-in-wallets-apple-pay-overview)** - Learn about using Apple Pay with Payabli

- **[Manage Apple Pay (API)](/guides/pay-in-developer-wallets-apple-pay-manage)** - Learn about managing Apple Pay and payment method domains via the Payabli API