---
updatedAt: 2026-04-23T13:43:44.000Z
agentTools:
  projectIndex: https://docs.br-dge.io/llms.txt
---

# Get Apple Pay token metadata

Apple Pay tokens contain encrypted data that only BR-DGE can decrypt. This endpoint lets you access that previously encrypted data, along with Bank Identifier Number (BIN) lookup data derived from the decrypted Apple Pay DPAN. This is particularly useful for performing your own pre-payment checks.

# OpenAPI definition

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "BR-DGE Payment Instrument REST API",
    "description": "REST API that deals with everything related to payment instrument tokenization\n",
    "version": "v1.0.0",
    "contact": {
      "name": "Customer Support",
      "url": "https://comcarde.atlassian.net/servicedesk/customer/portals"
    },
    "license": {
      "name": "MIT",
      "url": "https://docs.br-dge.io/docs/openapi-license"
    }
  },
  "servers": [
    {
      "url": "https://sandbox.comcarde.com/v1",
      "description": "Sandbox subdomain for testing your integration works as expected, using mock payment instruments only.\n"
    },
    {
      "url": "https://secure.comcarde.com/v1",
      "description": "Use this subdomain for processing live payments in the EU region."
    },
    {
      "url": "https://secure-amer-01.api.br-dge.io/v1",
      "description": "Use this subdomain for processing live payments in the NA region."
    }
  ],
  "tags": [
    {
      "name": "Payment Instrument Tokenization",
      "description": "Payment instrument tokenization is the practice of securely storing card details, and providing a unique token that can be used in place of the raw payment instrument.\n"
    }
  ],
  "externalDocs": {
    "url": "https://docs.br-dge.io"
  },
  "paths": {
    "/payment-instruments/apple-pay/query": {
      "post": {
        "tags": [
          "Payment Instrument Tokenization"
        ],
        "summary": "Get Apple Pay token metadata",
        "description": "Apple Pay tokens contain encrypted data that only BR-DGE can decrypt. This endpoint lets you access that previously encrypted data, along with Bank Identifier Number (BIN) lookup data derived from the decrypted Apple Pay DPAN. This is particularly useful for performing your own pre-payment checks.",
        "operationId": "queryApplePayDetailsPOST",
        "security": [
          {
            "ServerApiKey": []
          }
        ],
        "requestBody": {
          "description": "Apple Pay token",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ApplePayTokenRequest"
              },
              "examples": {
                "apple-pay-token-nonce": {
                  "summary": "Apple Pay PSP-bound nonce",
                  "value": {
                    "token": "XX#868e8b42-d8bc-470c-9b84-49bf6d4e9a23"
                  }
                },
                "apple-pay-raw-token": {
                  "summary": "Apple Pay Raw Encrypted Token",
                  "value": {
                    "token": "{\"token\":{\"paymentData\":{\"data\":\"ZPqomcCPxM9cuWCEcWgZ..."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful retrieval of Apple Pay details",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApplePayDetails"
                },
                "examples": {
                  "full Apple Pay card metadata": {
                    "description": "Apple Pay full card metadata and decrypted payload",
                    "value": {
                      "decryptedPayload": {
                        "applicationPrimaryAccountNumber": "4818528840216497",
                        "applicationExpirationDate": "281231",
                        "currencyCode": "826",
                        "transactionAmount": 100,
                        "cardholderName": "John Smith",
                        "deviceManufacturerIdentifier": "040010030273",
                        "paymentDataType": "3DSecure",
                        "paymentData": {
                          "eciIndicator": 7
                        },
                        "transactionId": "31675461ec268fed0ca9699e632753447d1a1de0aa65170e049033d7a801d3f3"
                      },
                      "paymentMethod": {
                        "displayName": "MasterCard 0839",
                        "network": "MasterCard",
                        "type": "credit"
                      },
                      "metadata": {
                        "metadataType": "cardMetaData",
                        "cardBrand": "VISA",
                        "issuer": "ACMEBANK",
                        "type": "DEBIT",
                        "category": "CLASSIC",
                        "countryIsoA2": "GB",
                        "commercial": true,
                        "bin": "45678765"
                      },
                      "expiryDate": "12-28",
                      "fingerprint": "63c8563d876b993878e1b5506b5fc5826e9e46266daaadac018a71ed307748c6",
                      "fingerprintExtended": "63c8563d876b993878e1b5506b5fc5826e9e46266daaadac018a71ed307748c61228"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request - the request was in an invalid format or contained invalid information.\n\nIf have any questions about why you are receiving these responses, please raise a ticket with support on the BR-DGE Support Portal at <https://docs.br-dge.io/docs/support#contact-support> with the `id` from the response so we can track down the individual requests on our end.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "Bad request with wrong format error": {
                    "value": {
                      "code": "4000",
                      "message": "Invalid request",
                      "id": "5bbd919b637167ac",
                      "additionalErrorDetails": "Provided Apple Pay token is in unknown format. Supported formats: PSP bound nonce, raw JSON."
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedRequest"
          },
          "500": {
            "$ref": "#/components/responses/UnknownServerError"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ApplePayTokenRequest": {
        "type": "object",
        "properties": {
          "token": {
            "$ref": "#/components/schemas/ApplePayToken"
          }
        }
      },
      "ApplePayToken": {
        "description": "If you are directly integrating with Apple Pay APIs on your client app then please refer to our [Apple Pay REST API guide] for details on how to generate an Apple Pay token for BR-DGE Payments.\n\nAlternatively you can use the [BR-DGE Web SDK Apple Pay module] to directly generate Apple Pay tokens for BR-DGE Payments.\n\n[Apple Pay REST API guide]: https://docs.br-dge.io/docs/rest-api-apple-pay\n[BR-DGE Web SDK Apple Pay module]: https://docs.br-dge.io/docs/apple-pay-module\n",
        "type": "string",
        "example": "BR#00000000-0000-0000-0000-000000000000"
      },
      "ApplePayDetails": {
        "description": "Additional information about Apple Pay Payment Instruments.",
        "allOf": [
          {
            "$ref": "#/components/schemas/DetailsOfAssociatedCardPaymentInstrument"
          },
          {
            "type": "object",
            "description": "Decrypted Apple Pay information and card metadata\n",
            "properties": {
              "decryptedPayload": {
                "$ref": "#/components/schemas/ApplePayDecryptedPayload"
              },
              "paymentMethod": {
                "$ref": "#/components/schemas/ApplePayPaymentMethod"
              }
            }
          }
        ]
      },
      "ApplePayDecryptedPayload": {
        "type": "object",
        "description": "[Apple Pay decrypted payload] excluding sensitive fields, such as cryptogram\n\n[Apple Pay decrypted payload]: https://developer.apple.com/documentation/passkit_apple_pay_and_wallet/apple_pay/payment_token_format_reference#3949536\n",
        "required": [
          "applicationPrimaryAccountNumber",
          "applicationExpirationDate",
          "currencyCode",
          "transactionAmount",
          "deviceManufacturerIdentifier",
          "paymentDataType",
          "paymentData",
          "transactionId"
        ],
        "properties": {
          "applicationPrimaryAccountNumber": {
            "type": "string",
            "example": "4818528840216497",
            "description": "Device-specific account number of the card that funds this transaction"
          },
          "applicationExpirationDate": {
            "type": "string",
            "example": "281231",
            "description": "Card expiration date in the format YYMMDD"
          },
          "currencyCode": {
            "example": "826",
            "type": "string",
            "description": "ISO 4217 numeric currency code, as a string to preserve leading zeros"
          },
          "transactionAmount": {
            "example": 100,
            "type": "integer",
            "description": "Transaction amount in the lowest denomination of the given currency"
          },
          "cardholderName": {
            "example": "John Smith",
            "type": "string",
            "description": "Optional field containing cardholder's name if present"
          },
          "deviceManufacturerIdentifier": {
            "example": "040010030273",
            "type": "string",
            "description": "Hex-encoded device manufacturer identifier"
          },
          "paymentDataType": {
            "example": "3DSecure",
            "type": "string",
            "description": "Transaction type.\n\nEMV relates to POS terminal transactions. 3D-Secure relates to ecommerce transactions.\n",
            "enum": [
              "3DSecure",
              "EMV"
            ]
          },
          "paymentData": {
            "$ref": "#/components/schemas/ApplePayDecryptedPaymentData"
          },
          "transactionId": {
            "example": "31675461ec268fed0ca9699e632753447d1a1de0aa65170e049033d7a801d3f3",
            "type": "string",
            "description": "Transaction identifier, generated on the device.\n\nRetrieved from [header] of decoded Apple Pay token.\n\n[header]: https://developer.apple.com/documentation/passkit_apple_pay_and_wallet/apple_pay/payment_token_format_reference#3949539\n"
          }
        }
      },
      "ApplePayDecryptedPaymentData": {
        "type": "object",
        "description": "Detailed payment data, excluding cryptogram",
        "properties": {
          "eciIndicator": {
            "type": "integer",
            "example": 7,
            "description": "Optional. ECI indicator, as defined by 3D-Secure.\n\nThe card network may add an ECI indicator to the payment data that the payment token includes.\n"
          }
        }
      },
      "ApplePayPaymentMethod": {
        "type": "object",
        "description": "Details from the `paymentMethod` section of the ApplePay token",
        "properties": {
          "displayName": {
            "type": "string",
            "example": "MasterCard 0839"
          },
          "network": {
            "type": "string",
            "example": "MasterCard"
          },
          "type": {
            "type": "string",
            "example": "credit"
          }
        }
      },
      "DetailsOfAssociatedCardPaymentInstrument": {
        "type": "object",
        "description": "Reusable details which can be returned on various card payment instrument backed payment instrument types. All details which are returned here are considered obfuscated.\n",
        "properties": {
          "metadata": {
            "$ref": "#/components/schemas/CardMetadata"
          },
          "expiryDate": {
            "$ref": "#/components/schemas/CardExpiryDate"
          },
          "fingerprint": {
            "$ref": "#/components/schemas/Fingerprint"
          },
          "fingerprintExtended": {
            "$ref": "#/components/schemas/FingerprintExtended"
          }
        }
      },
      "FingerprintExtended": {
        "type": "string",
        "description": "A fingerprint with card expiry date appended in MMYY format.\n"
      },
      "ErrorResponse": {
        "title": "ErrorResponse",
        "type": "object",
        "properties": {
          "additionalErrorDetails": {
            "type": "string",
            "description": "Additional information that may sometimes be returned about the reason an error occurred."
          },
          "code": {
            "$ref": "#/components/schemas/Code"
          },
          "id": {
            "$ref": "#/components/schemas/RequestId"
          },
          "message": {
            "$ref": "#/components/schemas/Message"
          },
          "validationErrors": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "description": "An object that contains validation errors"
          }
        }
      },
      "CardMetadata": {
        "type": "object",
        "description": "If a card payment instrument is used then BR-DGE may be able to provide metadata about the card\n\n**Please note: All text will be UPPERCASE and all fields can be null**\n",
        "properties": {
          "metadataType": {
            "type": "string",
            "description": "Discriminator field. Discriminator field. Please see the discriminator mapping for the PaymentInstrumentMetadata schema.\n"
          },
          "cardBrand": {
            "type": "string",
            "example": "MASTERCARD",
            "description": "MASTERCARD, VISA, etc"
          },
          "issuer": {
            "type": "string",
            "description": "Name of issuing bank"
          },
          "type": {
            "type": "string",
            "enum": [
              "DEBIT",
              "CREDIT",
              "CHARGE_CARD",
              "CHARGE",
              "DEFERRED_DEBIT",
              "PREPAID",
              "PREPAID_RELOADABLE",
              "UNKNOWN"
            ]
          },
          "category": {
            "type": "string",
            "example": "CLASSIC",
            "description": "CLASSIC, BUSINESS, MIXED_PRODUCT, etc"
          },
          "countryIsoA2": {
            "type": "string",
            "description": "ISO 3166 Alpha-2 Country code",
            "example": "GB"
          },
          "commercial": {
            "type": "boolean",
            "description": "Indicates if the card is corporate or retail",
            "example": true
          },
          "bin": {
            "type": "string",
            "description": "The Bank Identification Number that identifies the bank or financial institution that issued the card",
            "example": "48321456",
            "pattern": "^[0-9]+$",
            "minLength": 6,
            "maxLength": 8
          }
        }
      },
      "CardExpiryDate": {
        "type": "string",
        "example": "05-25",
        "description": "Card expiry date in MM-YY format.\n"
      },
      "Fingerprint": {
        "type": "string",
        "maxLength": 64,
        "description": "A unique token that can be used to detect if two BR-DGE tokens represent the same underlying Payment Instrument.\n",
        "example": "63c8563d876b993878e1b5506b5fc5826e9e46266daaadac018a71ed307748c6"
      },
      "Message": {
        "type": "string",
        "description": "A description of the outcome of the request."
      },
      "RequestId": {
        "type": "string",
        "description": "The ID of this request. If you can include these when querying the outcome of individual requests, we can track down the root cause faster.\n",
        "example": "a7f45953-1e8b-4f33-87b0-3293f4f6972f"
      },
      "Code": {
        "type": "string",
        "description": "[Response Code](https://docs.br-dge.io/docs/response-codes) signifying the outcome of the request.",
        "example": "1000"
      }
    },
    "responses": {
      "UnauthorizedRequest": {
        "description": "Unauthorized request."
      },
      "UnknownServerError": {
        "description": "An internal server error occurred upstream while processing the request.\n\nIf you have any questions about why you are receiving these responses, please raise a ticket with support on the BR-DGE Support Portal at <https://comcarde.atlassian.net/servicedesk/customer/portals> with the `id` from the response so we track down the individual requests on our end.\n",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "examples": {
              "Internal server error": {
                "description": "This example shows the [5001 error code]\n\nA full list of possible response codes is available [here].\n\n[5001 error code]: https://docs.br-dge.io/docs/response-codes#5001\n[here]: https://docs.br-dge.io/docs/response-codes\n",
                "value": {
                  "code": "5001",
                  "message": "Unexpected error",
                  "id": "4fad8e2e06a15656"
                }
              }
            }
          }
        }
      }
    },
    "securitySchemes": {
      "ServerApiKey": {
        "type": "http",
        "scheme": "bearer",
        "description": "Operations intended for use by Merchant servers.\n\n**IMPORTANT** This key allows you to perform sensitive operations such as authorizing payments and refunds.\n\n**Production Server API keys must not be accessible outside your organization.**\n"
      }
    }
  }
}
```