Skip to main content

Alternative payment methods

PayPal and Apple Pay are collected by the provider, not by SecureFields. The customer approves the payment in the PayPal window or the Apple Pay sheet, and the provider SDK returns a reference. You integrate the provider client-side, then send that reference to the Payment API in the split item.

This flow supports two payment methods:

Payment methodpartnermethodPayload object
PayPalpaypalwalletpaypal
Apple Payadyenapplepayapplepay

Apple Pay is processed by an acquirer, adyen today.

Flow overview​

Before you start​

  • Ask your Purse Integration Team to enable the payment method on your entity and confirm which partner processes it.
  • Create your own PSP account and credentials. The provider SDK runs under your merchant account.
  • For Apple Pay, complete Apple's merchant requirements with your acquirer: merchant ID, domain validation, and merchant identity certificate.

Step 1 — Check eligibility​

Call /payment/v2/eligible-solutions before rendering the button. Eligibility covers the order and the entity, not the device: Apple Pay also needs a supporting browser and a provisioned card, which ApplePaySession.canMakePayments() reports.

const { eligible_solutions } = await fetchEligibleSolutions(order, customer);

const paypal = eligible_solutions.find(s => s.partner === 'paypal' && s.method === 'wallet');
const applePay = eligible_solutions.find(s => s.method === 'applepay');
const deviceSupportsApplePay = window.ApplePaySession && ApplePaySession.canMakePayments();

if (paypal) renderPayPalButtons();
if (applePay && deviceSupportsApplePay) renderApplePayButton(applePay.partner);

On the PayPal side, paypal.Buttons().isEligible() reports whether the JS SDK will render the button for the current payer.

Retrieve payment methods documents the full request and response.

Step 2 — Collect the payload from the provider​

PayPal​

Create the order server-side with the Orders v2 API and render the buttons with the PayPal JavaScript SDK. The customer approves in the PayPal window, which gives you an order ID. Send it as paypal.order_id.

To save the customer's PayPal account for later payments, add PayPal's save payment method flow. Your server creates a vault setup token, the customer approves it with the order, and you send its ID as paypal.setup_token_id.

order_id and setup_token_id

order_id carries the order that gets authorized. setup_token_id carries the PayPal account to vault, so send both fields when the customer approved saving it. A one-off payment carries order_id alone.

PayPal resources

Apple Pay​

Implement Apple Pay on the Web, or PKPaymentRequest in a native app, and follow your acquirer's API-only guide. The Apple Pay sheet returns an encrypted payment token. Send it as applepay.token.

With Adyen as the partner, follow Apple Pay for API only and configure the certificate as described in Apple Pay certificate.

Apple Pay resources

Step 3 — Create the payment​

Send the payload in the split item. amount, partner, and method are required. The payload object replaces the vault_form_token used for cards.

PayPal​

curl -X POST 'https://api.purse-sandbox.com/payment/v2/payments' \
  --header 'Content-Type: application/json' \
  --header "x-api-key: ${API_KEY}" \
  --header "Authorization: Bearer ${ACCESS_TOKEN}" \
  --data-raw '{
    "entity_id": "${ENTITY_ID}",
    "amount": 3299,
    "currency": "EUR",
    "order": {
      "reference": "order-456",
      "net_amount": 3299,
      "tax_amount": 549
    },
    "split": [
      {
        "amount": 3299,
        "partner": "paypal",
        "method": "wallet",
        "paypal": {
          "order_id": "${PAYPAL_ORDER_ID}",
          "setup_token_id": "${PAYPAL_SETUP_TOKEN_ID}"
        }
      }
    ]
  }'

Apple Pay​

curl -X POST 'https://api.purse-sandbox.com/payment/v2/payments' \
  --header 'Content-Type: application/json' \
  --header "x-api-key: ${API_KEY}" \
  --header "Authorization: Bearer ${ACCESS_TOKEN}" \
  --data-raw '{
    "entity_id": "${ENTITY_ID}",
    "amount": 3299,
    "currency": "EUR",
    "order": {
      "reference": "order-456",
      "net_amount": 3299,
      "tax_amount": 549
    },
    "split": [
      {
        "amount": 3299,
        "partner": "adyen",
        "method": "applepay",
        "applepay": {
          "token": "${APPLE_PAY_TOKEN}"
        }
      }
    ]
  }'
API Endpoint

Field mapping​

FieldRequiredDescription
split[].amountYesAmount for this split item, in currency minor units (3299 = 32.99 EUR)
split[].partnerYesPartner that processes the method, from eligible_solutions: paypal, adyen
split[].methodYesPayment method: wallet for PayPal, applepay for Apple Pay
split[].paypal.order_idPayPalID of the PayPal order the customer approved
split[].paypal.setup_token_idNoID of the PayPal vault setup token, when the customer approved saving their account
split[].applepay.tokenApple PayEncrypted payment token returned by the Apple Pay sheet
split[].save_tokenNotrue to save the payment method in the customer's wallet, if the partner supports it
Fields that do not apply

The provider authenticates the customer, so an APM split item carries no vault_form_token and no three_ds_authentication_options. The browser object, required for card 3DS, does not apply either.

Step 4 — Handle the outcome​

The response carries the authorization status. Under authorization.partner_transactions, each entry holds the transaction created at the partner and its partner_reference.

Final status via webhook

Subscribe to the payment.updated webhook event for the final status. See Webhooks.

Capture, void, and refund follow each partner's capabilities. Both support full and partial capture. Apple Pay via Adyen voids only the full remaining authorized amount and allows a single refund. See PayPal Wallet and Apple Pay via Adyen.

Next steps​