Apple Pay Web

​

Overview

​

Integration overview

1. Register the user. Call the create-user endpoint with the user’s name, email, address, and phone number.
   • Store the returned Push id alongside your internal user record.
   • Register each user only once and reuse the user’s id on every subsequent transaction.
2. Initialize the Apple Pay launcher. Call the create-user-url endpoint with the user’s id and type: "apple_pay" when the user loads the payment page, then initialize the SDK launcher with the returned url.
   • Check ApplePaySession.canMakePayments() and render the Apple Pay button only when it returns true. For styling and placement, follow Apple’s design guidelines and JavaScript guide.
   • To support non-Apple devices or browsers other than Safari, install the Apple Pay JS SDK on your cashier. Initiating the payment then displays a QR code the user scans with an Apple device to authorize.
3. Display the payment sheet. When the user clicks the Apple Pay button, call launcher.display() with the payment amount, currency, direction, and an onAuthorize callback. The SDK handles merchant validation and presents the payment sheet.
   • Optionally pass an onComplete callback that runs when the payment sheet is dismissed.
4. Authorize the payment. The onAuthorize callback receives a token once the user approves with Face ID or Touch ID. Pass the token, along with the same amount, currency, and direction, to the authorize-payment endpoint from your backend.
   • Return the resulting status (approved or declined) from onAuthorize to complete the Apple Pay session. The amount and currency sent to /authorize must match the values passed to display().

curl --request POST \
  --url https://sandbox.pushcash.com/user \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": {
    "first": "Alfred",
    "last": "Hitchcock"
  },
  "email": "alfred@imdb.com",
  "address": {
    "address_line_1": "1609 10th Ave",
    "locality": "Bodega Bay",
    "administrative_area": "CA",
    "postal_code": "94923",
    "country": "US"
  },
  "phone_number": "(555) 681-3485",
  "tag": "4c8e6b4f"
}
'

curl --request POST \
  --url https://sandbox.pushcash.com/user/{id}/url \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "type": "apple_pay"
}
'

curl --request POST \
  --url https://sandbox.pushcash.com/authorize \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "amount": 1000,
  "currency": "USD",
  "direction": "cash_in",
  "token": "token_mbDRHFi3dxIZEtykHsgUGC"
}
'

{
  "id": "user_lVpbPL0K1XIiHx0DxipRbD"
}

{
  "url": "https://cdn.pushcash.com/applepay/?param=1&param=2&param=3"
}

{
  "id": "intent_sandbox_mbDRHFi3dxIZEtykHsgUGC",
  "status": "approved"
}

{
  "id": "intent_sandbox_mbDRHFi3dxIZEtykHsgUGC",
  "status": "declined"
}

​

Launcher and payment sheet

// On page load: instantiate the launcher from the create-user-url response.
let applePay;
try {
  applePay = new window.PushCash.ApplePay({ url });
  submitButton.disabled = false;
} catch (error) {
  submitButton.disabled = true;
  callbackResponse.textContent = `Apple Pay init error: ${error.message}`;
}

// On button click (a user gesture): present the payment sheet.
submitButton.addEventListener('click', () => {
  if (!applePay) return;

  applePay.display({
    amount: 1000,            // amount of payment in cents
    direction: 'cash_in',
    currency: 'USD',
    onAuthorize: async (tokenId) => {
      // send tokenId to your backend, which calls POST /authorize
      const result = await yourBackend.authorize(tokenId);
      return result.status; // 'approved' or 'declined'
    },
    onComplete: async () => {
      // reset your UI after the payment sheet is dismissed
      submitButton.disabled = true;
    },
  });
});

​

Domain registration

1. Supply your domain. Give your Push Cash representative the exact domain your cashier is served from (for example, cashier.your-domain.com). For sandbox, email hello@pushcash.com.
2. Receive the domain association file. Push generates and sends you the apple-developer-merchantid-domain-association.txt file for that domain over Slack or email.
3. Host the file. Place it at:
   https://your-domain.com/.well-known/apple-developer-merchantid-domain-association.txt
   
4. Push verifies the domain. Once the file is reachable over HTTPS, Push verifies the domain in the Apple developer console. This must be done by Push — it is not self-serve.

​

Withdrawals

1. Display stored credentials. Call the list-user-credentials endpoint with the user’s ID, passing apple_pay_debit as a type query parameter (?type=apple_pay_debit). Render the returned credentials so the user can pick which card to withdraw to.
   • Only deposits made with a debit card create an apple_pay_debit credential. Deposits made with a credit card do not create a withdrawal-eligible credential.
2. Submit the withdrawal. Call the authorize-payment endpoint with the selected credential_id, direction: cash_out, and the amount.
   • A 200 response means the withdrawal was approved — display the result to the user.
   • Handle a 401 response. In a small number of cases the debit card does not support OCT (Original Credit Transactions), which are required to push funds to a card. This is determined by the card issuer and cannot be resolved for that card — prompt the user to select or add a different debit card.

curl --request GET \
  --url 'https://sandbox.pushcash.com/user/{id}/credentials?type=apple_pay_debit' \
  --header 'Authorization: Bearer <token>'

curl --request POST \
  --url https://sandbox.pushcash.com/authorize \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "user_id": "user_lVpbPL0K1XIiHx0DxipRbD",
  "credential_id": "cred_sandbox_123",
  "amount": 2500,
  "currency": "USD",
  "direction": "cash_out"
}
'

{
  "data": [
    {
      "id": "cred_7YlA9IiSl8UZvNwNSbFajV",
      "created_at": "2023-05-24T20:15:18.158Z",
      "card_last4": "4444",
      "authenticated": true,
      "type": "apple_pay_debit",
      "account_last4": null,
      "bank_name": null
    }
  ]
}

​

Sandbox testing

​

Simulating a stored credential

curl --request POST \
  --url https://sandbox.pushcash.com/sandbox/credential \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "user_id": "user_lVpbPL0K1XIiHx0DxipRbD",
  "type": "apple_pay_debit",
  "card_last4": "9010"
}
'

​

Integration checklist

• Simulate an approved deposit by submitting a payment for $10.00
• Simulate a declined deposit by submitting a payment for $22.00
• Create an apple_pay_debit credential using the simulate-credential endpoint, verify it is returned by list-user-credentials with ?type=apple_pay_debit and displayed with card_last4, and test a withdrawal to it
• Test an OCT decline by submitting a cash_out for 2200 cents ($22.00) against an apple_pay_debit credential

​

Next steps

• Set up webhooks to receive asynchronous updates about payment status — see the enabling webhooks guide.
• Move your integration from sandbox to production with the Go-Live Checklist.