Apple Pay

​

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;
    },
  });
});

​

Withdrawals

1. Display stored credentials. Call the list-user-credentials endpoint with the user’s ID, then filter the results for credentials with type apple_pay_debit — only these can receive a withdrawal. Render them so the user can pick which card to withdraw to.
   • For apple_pay_debit credentials, card_last4 is the last four digits of the user’s FPAN (the physical card number), not the device-specific token (DPAN) Apple generates. Display card_last4 so the user recognizes their card.
   • Credentials created from a credit card have type apple_pay and cannot receive withdrawals — exclude them from the selection UI.
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 \
  --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
    },
    {
      "id": "cred_8ZlB0JjTm9VZaOxOTcGbkW",
      "created_at": "2023-05-25T10:20:30.123Z",
      "card_last4": "1234",
      "authenticated": true,
      "type": "apple_pay",
      "account_last4": null,
      "bank_name": null
    }
  ]
}

​

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.

​

Sandbox testing

• 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 by depositing with a debit card from your Apple Wallet, verify it is displayed with card_last4, and test a withdrawal to it
• Create an apple_pay credential by depositing with a credit card, and verify it is not presented for withdrawals
• 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.