Add payment card to Apple wallet

Add Payment Card to Apple Wallet

This endpoint provisions a Netevia payment card into Apple Wallet using the Apple Pay in-app provisioning flow. The caller supplies the payment card identifier along with the cryptographic certificates, nonce, and nonce signature generated by the PassKit framework on the device. Netevia forwards these values to the card network to complete the tokenization handshake.

Endpoint

POST /api/paymentCards/addToAppleWallet

Authentication

Bearer token required. Obtain via:

POST https://api.banking.netevia.dev/api/auth/v2

Include in header: Authorization: Bearer {token}
Token lifetime: 10 minutes. Refresh via POST /api/auth/refresh.

When to use

Use this endpoint when a mobile application user initiates an "Add to Apple Wallet" action for one of their Netevia payment cards. It should be called after the iOS PassKit framework returns the leaf and sub-CA certificates, nonce, and nonce signature from PKAddPaymentPassViewController. This applies to Physical, Virtual, and Burner card types.

Request Body

{
  "paymentCardId": "card_a1b2c3d4e5f6g7h8",
  "sertificates": [
    "MIICxDCCAaygAwIBAgIIVqpBMEGKfmwwDQYJKoZIhvcNAQELBQAwIzEhMB8GA1UE...",
    "MIIBwjCCAWigAwIBAgIIR5VqBNEGKfmwwCgYIKoZIzj0EAwIwIzEhMB8GA1UE..."
  ],
  "nonce": "bm9uY2VWYWx1ZUhlcmU=",
  "nonceSignature": "c2lnbmF0dXJlVmFsdWVIZXJl"
}

Response

200 OK

A 200 response indicates the provisioning request was successfully submitted to the card network. The response body confirms success and may contain the encrypted pass data required to complete the PassKit provisioning flow on the device.

{
  "success": true
}

Error Codes

Common Mistakes

• Misspelling the sertificates field — the schema uses sertificates (not certificates); sending the correct spelling will cause the field to be ignored and return a 400 error.
• Sending an empty array for sertificates — at least the leaf certificate and sub-CA certificate from PassKit must be included.
• Calling this endpoint before the iOS PassKit framework has returned the certificates, nonce, and nonce signature; collect all values from PKAddPaymentPassViewControllerDelegate first.
• Using a card ID that belongs to a different customer's account — the token's identity must match the cardholder who owns the specified paymentCardId.

Related Endpoints

• POST /api/paymentCards/addToGoogleWallet — Provision a payment card into Google Wallet
• GET /api/paymentCards/{paymentCardId} — Retrieve details and current status of a payment card
• POST /api/paymentCards — Create a new Virtual or Burner payment card

Example

curl -X POST https://api.banking.netevia.dev/api/paymentCards/addToAppleWallet \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "paymentCardId": "card_a1b2c3d4e5f6g7h8",
    "sertificates": [
      "MIICxDCCAaygAwIBAgIIVqpBMEGKfmwwDQYJKoZIhvcNAQELBQAwIzEhMB8GA1UE...",
      "MIIBwjCCAWigAwIBAgIIR5VqBNEGKfmwwCgYIKoZIzj0EAwIwIzEhMB8GA1UE..."
    ],
    "nonce": "bm9uY2VWYWx1ZUhlcmU=",
    "nonceSignature": "c2lnbmF0dXJlVmFsdWVIZXJl"
  }'