Apple Pay on the Web
Interactive Demo

Disbursements

Implement the Disbursement Request API to disburse funds to your customer. With the Disbursement Request API, you can allow your site visitors to transfer funds from your site to an account that is linked to a card in Wallet. The Disbursement Request API is only available as a subset of the Payment Request API.

Requirements

This demo uses the Disbursement Request API, and to run this demo you need to use:

• iOS devices running iOS 18 or later
• Safari 18 with macOS 15 or later

Display an Apple Pay button

To display an Apple Pay button, use the following code to load the button script into your web page from the content delivery network:

<script crossorigin
        src="https://applepay.cdn-apple.com/jsapi/1.latest/apple-pay-sdk.js"
        ></script>

The JavaScript Apple Pay button provides a variety of Apple Pay button types that you can use on your website to initiate a transaction. You can specify the Apple Pay button style, type, and localization using attributes. Use CSS to set other properties, such as the size and corner radius. Using the official Apple Pay button element ensures your site displays the latest style, renders correctly across devices, and follows Apple guidelines. For design guidance, see Human Interface Guidelines > Apple Pay > Buttons and Marks.

Try it: Display settings

Use the following tools to try the different display settings on the button below:

<style>
apple-pay-button {
  --apple-pay-button-width: 150px;
  --apple-pay-button-height: 30px;
  --apple-pay-button-border-radius: 3px;
  --apple-pay-button-padding: 0px 0px;
  --apple-pay-button-box-sizing: border-box;
}
</style>
<apple-pay-button buttonstyle="black" type="plain" locale="en-US"></apple-pay-button>

Create a Disbursement Request

A disbursement request requires the construction of a PaymentRequest when your customer clicks or taps the Apple Pay button.

const request = new PaymentRequest(methods, details, options);
    

The PaymentRequest constructor takes three arguments:

• The disbursement methods you support
• The details to show to your customer (like disbursement amount and IFO fee)
• The options you require

Disbursement method

Disbursement methods represent the means by which you can send payments to your customer using the Disbursement Request API. You specify the disbursement methods you accept as a sequence of PaymentMethodData dictionaries, each of which contains an identifier (supportedMethods) and associated information (data).

To disburse payments using Apple Pay through the Disbursement Request API, include Apple Pay as a payment method. Apple Pay’s URL-based payment method identifier is "https://apple.com/apple-pay", and its associated data is an ApplePayRequest dictionary.

Safari supports the Apple Pay Disbursement payment method in the PaymentRequest schema. Other browsers may support additional methods. The system determines which payment methods to present based on the capabilities of the device and on user preferences when specifying more than one method.

Disbursement requests can support Instant Funds Out (IFO). With IFO support, you can offer your customer the option to have disbursement funds instantly transferred to the customer’s card, provided the customer pays a convenience fee. Add supportsInstantFundsOut to the list of merchantCapabilities to construct an IFO disbursement. The merchantCapabilities setting can also restrict a disbursement to specific card types, such as limiting a disbursement to debit cards.

Try it: Disbursement method

You may configure the values in the PaymentMethodData structure below.

Select “Basic disbursement request” to see a payment sheet with only the required fields. Select “Instant Funds Out request” to include the optional IFO field.

Click or tap the Apple Pay button below to see how the payment sheet displays information.

Disbursement details

Supply the disbursement details in the PaymentDetailsInit dictionary. It contains your transaction’s total amount and disbursement method-specific modifiers.

The total amount needs to be $0.00 or greater, and when using Apple Pay, all payment amounts in your request need to use the same ISO 4217 currency code. It’s your responsibility to ensure the correctness of your payment details; Safari doesn’t perform any currency calculations on your behalf.

Disbursement modifiers

Apple Pay can update your transaction’s additional line items and total when you include optional modifiers in your disbursement details. For example, you can adjust the total amount based on the type of disbursement, if the disbursement includes an IFO fee.

Modifiers provide some of the functionality present in the paymentmethodselected event. For more information, see ApplePayModifier.

When constructing a disbursement request, add a disbursementRequest key with an empty dictionary value to your list of modifiers. This key identifies the request as a disbursement request, in which funds are being disbursed from a merchant to a customer, instead of a typical payment request.

Optionally, to require additional contact information from a recipient of a disbursement, include a requiredRecipientContactFields key within the disbursementRequest dictionary. You can request information such as the recipient’s name, email address, or phone number. The value of the optional requiredRecipientContactFields key should be an array that lists one or more of the following contact fields: email, name, phone, phoneticName, and postalAddress. After requesting the recipient’s information, you can push the information to the payment sheet to convey the context of a disbursement to a customer.

For example, a disbursement request could also take place in a transfer of funds flow that involves your customer disbursing funds to one of their contacts. A customer could elect to send a link to a contact who may not be an existing user of your service. When the recipient of the disbursement claims the funds, you may offer the recipient incentives to join your service during the process of accepting the funds transfer. Pulling the recipient’s contact information from Apple Pay, in this context, can help streamline your service’s sign-up process by using the recipient’s information to autofill a sign-up form.

If your disbursement supports IFO, you can set up the disbursement to include an IFO fee when your customer opts for an instant transfer of funds. Use additionalLineItems to differentiate a disbursement amount from an IFO fee. Set the value of the disbursementLineItemType to instantFundsOutFee to represent the amount of an IFO fee. For a disbursement amount, set disbursementLineItemType to disbursement. The disbursement’s total is the remaining amount after an IFO fee is deducted.

Try it: Disbursement details

Modify the values in the PaymentDetailsInit structure below and click or tap the Apple Pay button to view the payment sheet.

Disbursement options

In a regular payment request, the PaymentOptions specifies the information to request from your customer, such as your customer’s name, email address, or phone number. However, PaymentOptions is not required for a disbursement request and setting these options will have no effect on the request—even if an option is set to true.

Try it: Disbursement options

You may configure the values in the PaymentOptions structure below.

Select ”Empty dictionary” or ”All options set to false” to see their effect on a payment sheet. Each selection should not affect the contact information requested from a disbursement’s recipient.

Requesting the recipient’s contact information during a disbursement solely depends on setting the requiredRecipientContactFields within the disbursement details. For more information, see Disbursement details.

Click or tap the Apple Pay button to see how the payment sheet displays information.

Complete merchant validation

Before you are able to display the payment sheet to the customer, you need to generate a valid payment session by interacting with Apple Pay servers. For security reasons, your server needs to do this interaction, not your browser client code, unlike everything else in this demo. To start the merchant validation process, call the show method on the PaymentRequest you created above.

After calling the show method, the browser invokes your onmerchantvalidation handler, which needs to fetch a merchant session from your server.

Refer to the instructions in Requesting an Apple Pay Payment Session to implement your server endpoint responsible for fetching the merchant session object from Apple Pay servers. If the fetch is successful, Apple Pay servers return a merchant session object, which your server needs to then pass back as the response to the browser.

You need to complete your onmerchantvalidation handler by passing the promise, containing the merchant session response, to the complete method on the event. The browser then displays the payment sheet.

The following code shows an example of how to validate a merchant to generate a payment session:

request.onmerchantvalidation = event => {
    // Call your own server to request a new merchant session.
    const merchantSessionPromise = fetch("/authorizeMerchant")
        .then(res => res.json()) // Parse the response as JSON.
        .catch(err => {
            console.error("Error fetching merchant session", err);
        });

    event.complete(merchantSessionPromise);
};
    

Respond to payment sheet interactions

After merchant validation is complete, Apple Pay provides the information about your customer’s payment sheet selections so that you can calculate the final transaction cost. The final details of a transaction may depend on the user’s disbursement method. To handle these adjustments, implement the onpaymentmethodchange event handler. You can determine the user’s selection using the PaymentRequest attribute.

When the browser calls one of these handlers, you need to call the event object’s updateWith callback function with a promise that resolves within 30 seconds to a PaymentDetailsUpdate; otherwise, the transaction times out.

Try it: Updating disbursement details

You may customize the PaymentDetailsUpdate below.

Select one of the Success options below (with or without updating additional line items and total) to see a successful response.

Click or tap the Apple Pay button to see how the payment sheet displays updates or address errors.

Authorize the disbursement

Finally, you receive a PaymentResponse through the show method’s returned promise to process the transaction. After the user authenticates the transaction using Face ID, Touch ID, or their device passcode, this promise resolves with the encrypted Apple Pay token, as well as any fields you request in the PaymentOptions. To finalize the transaction, you need to pass the encrypted payment token to your payment processor using their API.

After you receive the response from your payment processor, call the complete method on the response and pass in a status of success or fail.

You may also validate the user’s information, and invoke the complete method immediately, without calling the payment processor, if you detect a problem with the selected options (for example, if the user selects a payment card in a location that you don’t service).

The following code shows an example of passing a status to the complete method:

const response = await request.show();
const status = "success";
await response.complete(status);
    

Try it: Complete the disbursement

You may customize the complete response below.

Select Success to default to success. Select Failure to see a fail response.

Click or tap the Apple Pay button to see how the payment sheet completes the payment.