Create an Apple Pay session

PUT/v0.2/checkouts/{checkout_id}/apple-pay-session

Creates an Apple Pay merchant session for the specified checkout.

Use this endpoint after the customer selects Apple Pay and before calling ApplePaySession.completeMerchantValidation(...) in the browser. SumUp validates the merchant session request and returns the Apple Pay session object that your frontend should pass to Apple's JavaScript API.

Authorization

Use one of the following alternatives:

apiKey
oauth2

Authorization guide

Path parameters

checkout_idstringrequired
SumUp-generated id returned when creating a checkout. Use this value to retrieve, update, process, or deactivate the checkout.

Example: "4e425463-3e1b-431d-83fa-1e51c2925e99"

Body parameters

application/json

Merchant validation details from the Apple Pay session in the payer's browser.

contextstringrequired
format: hostname
Hostname of the website displaying the Apple Pay payment sheet, without a URL scheme or path. Use the domain registered for Apple Pay.

Example: "example.com"
targetstringrequired
format: uri
Apple Pay validation URL received as validationURL in the browser's onvalidatemerchant event.

Example: "https://apple-pay-gateway-cert.apple.com/paymentservices/startSession"

Responses

200application/json

Successful request. Returns the Apple Pay merchant session object that should be forwarded to the Apple Pay JS SDK to complete merchant validation and continue the payment flow.

400application/json

Bad Request

Exactly one of the following variants.

Error

View Error schema

messagestring
Short description of the error.

Example: "Resource not found"
error_codestring
Platform code for the error.

Example: "NOT_FOUND"

array<unknown>

404application/json

The requested resource does not exist.

messagestring
Short description of the error.

Example: "Resource not found"
error_codestring
Platform code for the error.

Example: "NOT_FOUND"

PUT

Create an Apple Pay session

Code sample

curl --request PUT \
  --url https://api.sumup.com/v0.2/checkouts/4e425463-3e1b-431d-83fa-1e51c2925e99/apple-pay-session \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "context": "example.com",
  "target": "https://apple-pay-gateway-cert.apple.com/paymentservices/startSession"
}
'

import SumUp from "@sumup/sdk";

async function main() {
  const client = new SumUp({ apiKey: "sup_sk_your_api_key" });

  const result = await client.checkouts.createApplePaySession(
    "4e425463-3e1b-431d-83fa-1e51c2925e99",
    {
      "context": "example.com",
      "target": "https://apple-pay-gateway-cert.apple.com/paymentservices/startSession"
    }
  );
  console.log(result);
}

main().catch(console.error);

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using SumUp;

public static class Program
{
    public static async Task Main()
    {
        using var client = new SumUpClient();
        var response = await client.Checkouts.CreateApplePaySessionAsync(
            "example-id",
            new CheckoutsCreateApplePaySessionRequest
            {
                Context = "example.com",
                Target = "https://apple-pay-gateway-cert.apple.com/paymentservices/startSession",
            });

        Console.WriteLine(response.StatusCode);
    }
}

import com.sumup.sdk.SumUpClient;

public final class CreateApplePaySessionSample {
  public static void main(String[] args) throws Exception {
    var client = new SumUpClient();

    var result = client.checkouts().createApplePaySession(
            "4e425463-3e1b-431d-83fa-1e51c2925e99",
            com.sumup.sdk.models.CreateApplePaySessionRequest.builder()
                .context("example.com")
                .target("https://apple-pay-gateway-cert.apple.com/paymentservices/startSession")
                .build()
        );
    System.out.println(result);
  }
}

import os

import sumup

client = sumup.Sumup(api_key=os.environ["SUMUP_API_KEY"])
result = client.checkouts.create_apple_pay_session(
    "4e425463-3e1b-431d-83fa-1e51c2925e99",
    context="example.com",
    target="https://apple-pay-gateway-cert.apple.com/paymentservices/startSession",
)
print(result)

<?php

declare(strict_types=1);

require __DIR__ . '/vendor/autoload.php';

$sumup = new \SumUp\SumUp('sup_sk_your_api_key');

$body = [
    'context' => 'example.com',
    'target' => 'https://apple-pay-gateway-cert.apple.com/paymentservices/startSession',
];

$result = $sumup->checkouts()->createApplePaySession(
    '4e425463-3e1b-431d-83fa-1e51c2925e99',
    $body,
);

var_dump($result);

package main

import (
	"context"
	"fmt"

	"github.com/sumup/sumup-go"
)

func main() {
	client := sumup.NewClient()
	result, err := client.Checkouts.CreateApplePaySession(context.TODO(), "4e425463-3e1b-431d-83fa-1e51c2925e99", sumup.CheckoutsCreateApplePaySessionParams{
		Context: "example.com",
		Target:  "https://apple-pay-gateway-cert.apple.com/paymentservices/startSession",
	})
	if err != nil {
		panic(err.Error())
	}

	fmt.Printf("%+v\n", result)
}

use sumup::{Authorization, Client};
#[tokio::main]
async fn main() {
    let client = Client::default()
        .with_authorization(Authorization::api_key("sup_sk_test_..."));
    let body = sumup::resources::checkouts::CreateApplePaySessionRequest::builder()
        .context("example.com")
        .target("https://apple-pay-gateway-cert.apple.com/paymentservices/startSession")
        .build();
    let response = client
        .checkouts()
        .create_apple_pay_session("CHECKOUT_ID", Some(body))
        .await
        .expect("create_apple_pay_session request failed");
    println!("{response:#?}");
}

Response example

{
  "displayName": "Test Account",
  "domainName": "pay.sumup.com",
  "epochTimestamp": 1775323532665,
  "expiresAt": 1775327132665,
  "merchantIdentifier": "7801D328E6637EFC1ADE6CE01C671D2CD318E32CA4ED1F9FC390D170D827D9AB",
  "merchantSessionIdentifier": "SSH92CC412E5FCF4FAB88684914C953C0D4_916523AAED1343F5BC5815E12BEE9250AFFDC1A17C46B0DE5A943F0F94927C24",
  "nonce": "a968a2bf",
  "operationalAnalyticsIdentifier": "Test Account:7801D328E6637EFC1ADE6CE01C671D2CD318E32CA4ED1F9FC390D170D827D9AB",
  "pspId": "7801D328E6637EFC1ADE6CE01C671D2CD318E32CA4ED1F9FC390D170D827D9AB",
  "retries": 0,
  "signature": "<apple-pay-signature>"
}

{
  "error_code": "INVALID",
  "message": "Bad Request"
}

{
  "error_code": "NOT_FOUND",
  "message": "Resource not found"
}