# Activate Apple Pay (API)

> Enable frictionless Apple Pay transactions through the Payabli API. Register domains, verify ownership, and activate Apple Pay service for your organization with step-by-step API instructions

<AudienceInfo audiences={['developers']} />

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.

<EndpointRequestSnippet endpoint="POST /PaymentMethodDomain" example="Paypoint" />

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

### 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:{/* break link */}//www{/* break link */}.{/* break link */}example.{/* break link */}com/monthlydues | www{/* break link */}.example.{/* break link */}com        |
| https\://{/* break link */}subdomain1{/* break link */}.example{/* break link */}.com/payments              | subdomain1{/* break link */}.example.{/* break link */}com |
| https\://{/* break link */}subdomain2{/* break link */}.example{/* break link */}.com/donations/pay         | subdomain2{/* break link */}.example.{/* break link */}com |
| https\:/{/* break link */}/subdomain3{/* break link */}.example{/* break link */}.com/order                 | subdomain3{/* break link */}.example.{/* break link */}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.

<Steps>
  <Step title="Download the domain-verification file">
    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)
  </Step>

  <Step title="Host the file on target domains">
    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:{/* break link */}//www{/* break link */}.example.{/* break link */}com/.{/* break link */}well-known/apple-developer-merchantid-domain-association
    * https:{/* break link */}//subdomain1.{/* break link */}example.{/* break link */}com/{/* break link */}.well-known/apple-developer-merchantid-domain-association
    * https{/* break link */}://subdomain2{/* break link */}.example.{/* break link */}com/.{/* break link */}well-known/apple-developer-merchantid-domain-association
    * https\:/{/* break link */}/subdomain3{/* break link */}.example{/* break link */}.com/.well-known/apple-developer-merchantid-domain-association
  </Step>
</Steps>

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).

<EndpointRequestSnippet endpoint="POST /PaymentMethodDomain/{domainId}/cascade" example="CascadeDomain" />

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"
      }
    ],
```

<Note>
  Payabli recommends a 10 second polling interval when checking domain cascade status.
</Note>

## 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 --request POST \
    --url https://api-sandbox.payabli.com/api/Wallet/applepay/configure-organization \
    --header 'Content-Type: application/json' \
    --header 'requestToken: <api-key>' \
    --data '{
    "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.

<AccordionGroup>
  <Accordion title="Prerequisites">
    * **[Apple Pay overview](/guides/pay-in-wallets-apple-pay-overview)** - Learn about using Apple Pay with Payabli
  </Accordion>

  <Accordion title="Next steps">
    * **[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
  </Accordion>
</AccordionGroup>