Card Metadata

Card metadata is information that describes a card, including its Bank Identification Number (BIN), network (such as Visa or Mastercard), funding type (credit, debit, or prepaid), and issuing bank and country. You can use this information to calculate transaction pricing or apply your own risk assessment rules.

There are two ways to retrieve card metadata:

• Before processing a transaction: perform a BIN lookup using a BIN, an encrypted card number, or an encrypted wallet token.
• After processing a transaction: read the card object on the related transaction object (such as CardTransaction), including within the initiateTransaction response.

Before processing a transaction

Use the REST BIN lookup endpoint when you need card metadata without initiating a payment. You can supply a BIN directly, an encrypted card number from Stitch Secure Fields, or an encrypted Apple Pay, Google Pay, or Samsung Pay token.

All three options use the same endpoint for both test and live clients:

POST https://api.stitch.money/v2/bin-lookups

Authentication

Follow the client token guide to obtain a client access token with the client_binlookup scope. Send requests from your backend with these headers:

Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

Keep your client credentials and access token on your server. Replace YOUR_ACCESS_TOKEN in the examples below with your client access token.

Choose a lookup input

Send one of the following fields in the JSON request body:

Field	Type	Description
bin	string	The first 6–8 digits of a card number. Use a string containing digits only.
cardNumber	string	The encrypted card number returned by Stitch Secure Fields, starting with ev:.
encryptedWalletToken	object	The wallet provider and its base64-encoded encrypted payment token. See wallet token lookups.

Look up a BIN

Pass the BIN as a string. The endpoint accepts 6, 7, or 8 digits; do not send a full card number in this field.

curl -X POST 'https://api.stitch.money/v2/bin-lookups' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "bin": "424242"
  }'

Look up an encrypted card number

Collect card details with Stitch Secure Fields and forward the encrypted card number to your backend. Send that value unchanged as cardNumber:

curl -X POST 'https://api.stitch.money/v2/bin-lookups' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "cardNumber": "ev:Tk9D:9QcRf9/EWSKp0R20:Am3ca5q/pdKvbCXhvcwAgeMMyCfBIE1Y/xmIJ77jUFy0:kh8FdcoXWTUKrY8tgQ3kUriOCr6JPgZTI8ErtSHtADc=:$"
  }'

Use the encrypted card number from Secure Fields: card.number on Web or card.encryptedNumber on the mobile typed APIs. Do not send a plaintext card number or base64-encode the encrypted value. The API extracts the BIN, so you do not need to supply bin, expiry, or CVC for this lookup.

Look up an encrypted wallet token

Set encryptedWalletToken.type to the wallet provider and encryptedWalletToken.value to the base64-encoded encrypted payment payload:

curl -X POST 'https://api.stitch.money/v2/bin-lookups' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "encryptedWalletToken": {
      "type": "apple_pay",
      "value": "eyJkYXRhIjoiMnBLdUtjbFE0QkVoc0d0NW9zenRWSjlUc0Y1NVY5UUVPSXpITFI1aS8xenovMVUraEpXKy95b2FHV0Q4MU9QN2pCR1lablpkRENNaG9sRGZ2a29nSDQ0bnBWVEFUenZjVU9HbEcyWHhxK1pHakhuV3lFaDZUWXl6NzdOT29KcnZRUGtYcW5Nc3doRGVDOVhmUThRNTlxMyt1UVRHL3Q4UW1semgyYytGSDI1dS9XMEJrZFp2S3FpTjZGbGR3bFpUdDlJM2UrY2pCaXY1dTlWemlJREEydmtMYW5YazV5WGRIOStPRkQxUFU1NHJrWEtJM3ZUY2hENU5Hay93dVdrMlNMNzRPSDhZZGpnUmtqVnpOSzd2aVQvb0ZIZlEvbEtBdndLNXVRN1huYzFQbDloWThvLy9OUm5NUFdPOFNXbVRZdmFnUnBmK2U5bUJMUGVOLzZESzFnbVJFYVpJMnhZaXl5SkZyeUtaZkZ4cTRZU2dpajBkaG9UTUg2Z3FlcVR2TndycUQ3aTlFelQxcmhNKyIsInNpZ25hdHVyZSI6Ik1JQUdDU3FHU0liM0RRRUhBcUNBTUlBQ0FRRXhEVEFMQmdsZ2hrZ0JaUU1FQWdFd2dBWUpLb1pJaHZjTkFRY0JBQUNnZ0RDQ0ErTXdnZ09Jb0FNQ0FRSUNDQlpqVElzT01GY1hNQW9HQ0NxR1NNNDlCQU1DTUhveExqQXNCZ05WQkFNTUpVRndjR3hsSUVGd2NHeHBZMkYwYVc5dUlFbHVkR1ZuY21GMGFXOXVJRU5CSUMwZ1J6TXhKakFrQmdOVkJBc01IVUZ3Y0d4bElFTmxjblJwWm1sallYUnBiMjRnUVhWMGFHOXlhWFI1TVJNd0VRWURWUVFLREFwQmNIQnNaU0JKYm1NdU1Rc3dDUVlEVlFRR0V3SlZVekFlRncweU5EQTBNamt4TnpRM01qZGFGdzB5T1RBME1qZ3hOelEzTWpaYU1GOHhKVEFqQmdOVkJBTU1IR1ZqWXkxemJYQXRZbkp2YTJWeUxYTnBaMjVmVlVNMExWQlNUMFF4RkRBU0JnTlZCQXNNQzJsUFV5QlRlWE4wWlcxek1STXdFUVlEVlFRS0RBcEJjSEJzWlNCSmJtTXVNUXN3Q1FZRFZRUUdFd0pWVXpCWk1CTUdCeXFHU000OUFnRUdDQ3FHU000OUF3RUhBMElBQk1JVmQrM3Ixc2V5SVk5bzNYQ1FvU0dOeDdDOWJ5d29QWVJnbGRsSzlLVkJHNE5DRHRnUjgwQitnek1mSEZURDkrc3lJTmE2MWRUdjlKS0ppVDU4RHhPamdnSVJNSUlDRFRBTUJnTlZIUk1CQWY4RUFqQUFNQjhHQTFVZEl3UVlNQmFBRkNQeVNjUlBrK1R2SitiRTlpaHNQNks3L1M1TE1FVUdDQ3NHQVFVRkJ3RUJCRGt3TnpBMUJnZ3JCZ0VGQlFjd0FZWXBhSFIwY0RvdkwyOWpjM0F1WVhCd2JHVXVZMjl0TDI5amMzQXdOQzFoY0hCc1pXRnBZMkV6TURJd2dnRWRCZ05WSFNBRWdnRVVNSUlCRURDQ0FRd0dDU3FHU0liM1kyUUZBVENCL2pDQnd3WUlLd1lCQlFVSEFnSXdnYllNZ2JOU1pXeHBZVzVqWlNCdmJpQjBhR2x6SUdObGNuUnBabWxqWVhSbElHSjVJR0Z1ZVNCd1lYSjBlU0JoYzNOMWJXVnpJR0ZqWTJWd2RHRnVZMlVnYjJZZ2RHaGxJSFJvWlc0Z1lYQndiR2xqWVdKc1pTQnpkR0Z1WkdGeVpDQjBaWEp0Y3lCaGJtUWdZMjl1WkdsMGFXOXVjeUJ2WmlCMWMyVXNJR05sY25ScFptbGpZWFJsSUhCdmJHbGplU0JoYm1RZ1kyVnlkR2xtYVdOaGRHbHZiaUJ3Y21GamRHbGpaU0J6ZEdGMFpXMWxiblJ6TGpBMkJnZ3JCZ0VGQlFjQ0FSWXFhSFIwY0RvdkwzZDNkeTVoY0hCc1pTNWpiMjB2WTJWeWRHbG1hV05oZEdWaGRYUm9iM0pwZEhrdk1EUUdBMVVkSHdRdE1Dc3dLYUFub0NXR0kyaDBkSEE2THk5amNtd3VZWEJ3YkdVdVkyOXRMMkZ3Y0d4bFlXbGpZVE11WTNKc01CMEdBMVVkRGdRV0JCU1VWOXR2MVhTQmhvbUpkaTkrVjRVSDU1dFlKREFPQmdOVkhROEJBZjhFQkFNQ0I0QXdEd1lKS29aSWh2ZGpaQVlkQkFJRkFEQUtCZ2dxaGtqT1BRUURBZ05KQURCR0FpRUF4dkFqeXlZVXV6QTRpS0ZpbUQ0YWsvRUZiMUQ2ZU0yNXVreWlRY3dVNGw0Q0lRQytQTkRmMFdKSDlrbEVkVGdPblVUQ0tLRUlrS09oM0hKTGkweTRpSmdZdkRDQ0F1NHdnZ0oxb0FNQ0FRSUNDRWx0TDc4Nm1OcVhNQW9HQ0NxR1NNNDlCQU1DTUdjeEd6QVpCZ05WQkFNTUVrRndjR3hsSUZKdmIzUWdRMEVnTFNCSE16RW1NQ1FHQTFVRUN3d2RRWEJ3YkdVZ1EyVnlkR2xtYVdOaGRHbHZiaUJCZFhSb2IzSnBkSGt4RXpBUkJnTlZCQW9NQ2tGd2NHeGxJRWx1WXk0eEN6QUpCZ05WQkFZVEFsVlRNQjRYRFRFME1EVXdOakl6TkRZek1Gb1hEVEk1TURVd05qSXpORFl6TUZvd2VqRXVNQ3dHQTFVRUF3d2xRWEJ3YkdVZ1FYQndiR2xqWVhScGIyNGdTVzUwWldkeVlYUnBiMjRnUTBFZ0xTQkhNekVtTUNRR0ExVUVDd3dkUVhCd2JHVWdRMlZ5ZEdsbWFXTmhkR2x2YmlCQmRYUm9iM0pwZEhreEV6QVJCZ05WQkFvTUNrRndjR3hsSUVsdVl5NHhDekFKQmdOVkJBWVRBbFZUTUZrd0V3WUhLb1pJemowQ0FRWUlLb1pJemowREFRY0RRZ0FFOEJjUmhCblhaSVhWR2w0bGdRZDI2SUNpNzk1N3JrM2dqZnhMaytFelZ0Vm1Xeld1SXRDWGRnMGlUbnU2Q1AxMkY4Nkl5M2E3Wm5DK3lPZ3BoUDlVUmFPQjl6Q0I5REJHQmdnckJnRUZCUWNCQVFRNk1EZ3dOZ1lJS3dZQkJRVUhNQUdHS21oMGRIQTZMeTl2WTNOd0xtRndjR3hsTG1OdmJTOXZZM053TURRdFlYQndiR1Z5YjI5MFkyRm5NekFkQmdOVkhRNEVGZ1FVSS9KSnhFK1Q1TzhuNXNUMktHdy9vcnY5TGtzd0R3WURWUjBUQVFIL0JBVXdBd0VCL3pBZkJnTlZIU01FR0RBV2dCUzdzTjZoV0RPSW1xU0ttZDYrdmV1djJzc2txekEzQmdOVkhSOEVNREF1TUN5Z0txQW9oaVpvZEhSd09pOHZZM0pzTG1Gd2NHeGxMbU52YlM5aGNIQnNaWEp2YjNSallXY3pMbU55YkRBT0JnTlZIUThCQWY4RUJBTUNBUVl3RUFZS0tvWklodmRqWkFZQ0RnUUNCUUF3Q2dZSUtvWkl6ajBFQXdJRFp3QXdaQUl3T3M5eWcxRVdtYkdHK3pYRFZzcGl2L1FYN2RrUGRVMmlqcjd4bklGZVFyZUorSmozbTFtZm1OVkJEWStkNmNMK0FqQXlMZFZFSWJDakJYZHNYZk00TzVCbi9SZDhMQ0Z0bGsvR2NtbUNFbTlVK0hwOUc1bkxtd21KSVdFR21ROEpraDBBQURHQ0FZZ3dnZ0dFQWdFQk1JR0dNSG94TGpBc0JnTlZCQU1NSlVGd2NHeGxJRUZ3Y0d4cFkyRjBhVzl1SUVsdWRHVm5jbUYwYVc5dUlFTkJJQzBnUnpNeEpqQWtCZ05WQkFzTUhVRndjR3hsSUVObGNuUnBabWxqWVhScGIyNGdRWFYwYUc5eWFYUjVNUk13RVFZRFZRUUtEQXBCY0hCc1pTQkpibU11TVFzd0NRWURWUVFHRXdKVlV3SUlGbU5NaXc0d1Z4Y3dDd1lKWUlaSUFXVURCQUlCb0lHVE1CZ0dDU3FHU0liM0RRRUpBekVMQmdrcWhraUc5dzBCQndFd0hBWUpLb1pJaHZjTkFRa0ZNUThYRFRJMk1Ea3hOekl4TkRrME1sb3dLQVlKS29aSWh2Y05BUWswTVJzd0dUQUxCZ2xnaGtnQlpRTUVBZ0doQ2dZSUtvWkl6ajBFQXdJd0x3WUpLb1pJaHZjTkFRa0VNU0lFSUVkdjRGYVdZeVl1SXpvOHFlcCswOElFSE9aWnJYd1J3VnF6bXE4a0dJMW9NQW9HQ0NxR1NNNDlCQU1DQkVjd1JRSWhBTldpYm5oTlVmd0FXQjJqSnNTdllrbTRZZGlZNTBPTlF3aHZJWTZDYVN3K0FpQWcyUHgzQzFqWG54TS96UHlnSWNodmJta3czM1ZxdVhDREZxQVMzWURVZHdBQUFBQUFBQT09IiwiaGVhZGVyIjp7InB1YmxpY0tleUhhc2giOiJkZzFLb0FzY29LNXlQWUVRZjBOM0lETkJSYy9vY0Q4cXNOcE9RVWJEZGNFPSIsImVwaGVtZXJhbFB1YmxpY0tleSI6Ik1Ga3dFd1lIS29aSXpqMENBUVlJS29aSXpqMERBUWNEUWdBRUhuUkxRM2pwdWVid1Z4cE9wTm80bEZSbENvdmFKOGliR1didDVWVkdpd3FWV3FkOTJlT3poM09yMStNSHdISmVlVzAzQ09TcDNXN1ArMTA4TzdRcldnPT0iLCJ0cmFuc2FjdGlvbklkIjoiZGY5M2QzODNiOWM3MTAzMjEzM2UyMzRmMzdhN2M4Y2MyMjU2ZGI3YjU5Y2ZkN2NmYjMwNTk4Y2RmNTBjM2MwYyJ9LCJ2ZXJzaW9uIjoiRUNfdjEifQ=="
    }
  }'

Use the appropriate provider and payload:

type	Payload to base64-encode
apple_pay	The JSON representation of the Apple Pay token's paymentData object, containing data, header, signature, and version.
google_pay	The encrypted token string in paymentMethodData.tokenizationData.token, containing the signed Google Pay token JSON.
samsung_pay	The JSON representation of the Samsung Pay 3DS credential object, containing data, version, and type.

Encode the payment payload itself, rather than the full wallet callback response. If your SDK already returns this payload as base64, forward it unchanged instead of encoding it again. For live Apple Pay and Google Pay lookups, your Stitch client must have the corresponding wallet merchant identifier configured.

For example, prepare an Apple Pay payload on a Node.js backend as follows. Here, paymentData is the token's encrypted payment data object:

const requestBody = {
  encryptedWalletToken: {
    type: 'apple_pay',
    value: Buffer.from(JSON.stringify(paymentData), 'utf8').toString('base64'),
  },
};

For Google Pay, the token is already a JSON string, so encode it directly without calling JSON.stringify on it:

const requestBody = {
  encryptedWalletToken: {
    type: 'google_pay',
    value: Buffer.from(paymentData.paymentMethodData.tokenizationData.token, 'utf8').toString(
      'base64'
    ),
  },
};

See the wallet integration guide for collecting wallet tokens. A wallet lookup uses the card number contained in the wallet token, which may be a network token number with a different BIN from the underlying physical card.

Response

All three input types return 201 Created with card metadata in the following fields. The values below are illustrative; metadata depends on the BIN:

{
  "bin": "424242",
  "network": "visa",
  "fundingType": "credit",
  "issuer": {
    "name": "Example Bank",
    "country": "ZA"
  }
}

Field	Description
bin	The BIN supplied in the request or extracted from the encrypted card number or wallet token.
network	visa, mastercard, amex, diners, or discover. May be null if unavailable or unrecognised.
fundingType	credit, debit, or prepaid. May be null if unavailable or unrecognised.
issuer.name	The issuer's name.
issuer.country	The issuer's country code, for example ZA.

The response contains BIN metadata and does not return the full card number or decrypted wallet payload.

After processing a transaction

Card metadata is available on the card object of a GraphQL CardTransaction. For example, include the following card fields when calling initiateTransaction to receive the metadata with the transaction response:

mutation InitiateCardTransaction($input: TransactionInitiateInput!) {
  initiateTransaction(input: $input) {
    ... on CardTransaction {
      id
      card {
        bin
        network
        type
        issuer {
          name
          country
        }
      }
    }
  }
}

Send this mutation to https://api.stitch.money/graphql with a client access token containing the transaction_initiate scope. Supply your card payment details in input; see once-off card payments with Secure Fields for a complete input example.

The same card object is also available when you fetch an existing CardTransaction, so you can retrieve its metadata later.