# Credit Cards

# Introduction
Credit cards are the most common forms of payment for all the types of transactions. It is enabled when the customer signs up for a merchant account with Braintree. This document covers the server-side implementation for credit cards using GraphQL

---
**Note**:If you are new to GraphQL please refer [About GraphQL ](https://graphql.braintreepayments.com/guides/#about-graphql) for more information. Also, for details on existing Server Support refer [Server Side Implementation](https://developer.paypal.com/braintree/docs/guides/credit-cards/server-side). For more information on basic concepts refer [Basic Concepts](https://graphql.braintreepayments.com/guides/#about-graphql).

---

# Card Verification
Before saving or modifying a payment method that uses a credit or debit card in the Vault, you can utilise card verification to ensure that the card data matches a legitimate, active account. 

**Note**: Credit Card verification must be done by following the below checks:
1. Open an account and get a valid credit card which matches all the criteria in the Vault.
2. Verify all the cards and customer can enable the card by using the [Verification Method](https://developer.paypal.com/braintree/articles/control-panel/vault/card-verification#enabling-card-verification) in the Control Panel
3. If the customer does not wish to verify all cards, one-time request is raised using the [verifyCreditCard](https://graphql.braintreepayments.com/reference/#Mutation--verifyCreditCard) mutation.
4. If you are using the Premium Fraud Management Tools, it's strongly recommend to pass [device_data](https://developer.paypal.com/braintree/docs/guides/premium-fraud-management-tools/server-side#using-device-data) each time you verify a card. If the user does not want to verify all cards by default,run one-time requests use [options.verify_card](https://developer.paypal.com/braintree/docs/reference/request/payment-method/create#options.verify_card) to perform [Creating a payment method](https://developer.paypal.com/braintree/docs/reference/request/payment-method/create#card-verification), [Updating a payment method](https://developer.paypal.com/braintree/docs/reference/request/payment-method/update#card-verification) , [Creating a customer](https://developer.paypal.com/braintree/docs/reference/request/customer/create#card-verification) , [Updating a customer](https://developer.paypal.com/braintree/docs/reference/request/customer/update#card-verification).
---
For further information related to Card verification please refer [Card Verification](https://developer.paypal.com/braintree/docs/guides/credit-cards/server-side#card-verification) method.

The gateway (GW) verifies cards by running either $0 or $1 authorization and then automatically voiding it. The user may specify a different options.verificationAmount for the authorization. This is shown in the below example:

*MutationCodeBlock*

mutation VerifyCreditCard($input: VerifyCreditCardInput!) {
  verifyCreditCard(input: $input) {
    clientMutationId
    verification {
      id
      legacyId
      status
      merchantAccountId
      createdAt
      gatewayRejectionReason
      paymentMethod {
        id
        createdAt
      }
      amount {
        value
        currencyIsoCode
        currencyCode
      }
      processorResponse {
        legacyCode
        message
        cvvResponse
        avsPostalCodeResponse
        avsStreetAddressResponse
      }
      networkResponse {
        code
        message
      }
    }
  }
}

*VariableCodeBlock*

{
  "input":{
    "paymentMethodId":"cGF5bWVudG1ldGhvZF9jY19rOHprcWpt"
  }
}

*ResponseCodeBlock*

{
  "data": {
    "verifyCreditCard": {
      "clientMutationId": null,
      "verification": {
        "id": "dmVyaWZpY2F0aW9uXzlqOG5tZ2pm",
        "legacyId": "9j8nmgjf",
        "status": "VERIFIED",
        "merchantAccountId": "paypal",
        "createdAt": "2022-08-10T00:55:52.000000Z",
        "gatewayRejectionReason": null,
        "paymentMethod": {
          "id": "cGF5bWVudG1ldGhvZF9jY19rOHprcWpt",
          "createdAt": "2022-08-04T21:17:51.000000Z"
        },
        "amount": {
          "value": "0.00",
          "currencyIsoCode": "USD",
          "currencyCode": "USD"
        },
        "processorResponse": {
          "legacyCode": "1000",
          "message": "Approved",
          "cvvResponse": "NOT_PROVIDED",
          "avsPostalCodeResponse": "MATCHES",
          "avsStreetAddressResponse": "NOT_PROVIDED"
        },
        "networkResponse": {
          "code": "XX",
          "message": "sample network response text"
        }
      }
    }
  },
  "extensions": {
    "requestId": "d4ec3b49-cb1b-4072-92d4-1dff2dce3de1"
  }
}

# Credit Card Transaction Methods
There are two methods used for credit card transaction:
* Create Transaction
* Create Advanced Transaction

## Create Transaction
Follow the steps to create a transaction:
1. Use [chargePaymentMethod](https://graphql.braintreepayments.com/reference/#Mutation--chargePaymentMethod) mutation to perform the credit card transaction.
2. Specify the amount and payment method nonce as explained on the client-side. Please refer [Client-Side](https://developer.paypal.com/braintree/docs/guides/credit-cards/client-side) guide for more information.

*MutationCodeBlock*

mutation ChargePaymentMethod($input: ChargePaymentMethodInput!) {
  chargePaymentMethod(input: $input) {
    transaction {
      status
      id
      legacyId
    }
  }
}

*VariableCodeBlock*

{
  "input": {
    "paymentMethodId": "fake-valid-nonce",
    "transaction": {
      "amount": 15.00
    }
  }
}

*ResponseCodeBlock*

{
    "data": {
        "chargePaymentMethod": {
            "transaction": {
                "status": "SUBMITTED_FOR_SETTLEMENT",
                "id": "dHJhbnNhY3Rpb25fMHQybmo5ejQ",
                "legacyId": "0t2nj9z4"
            }
        }
    },
    "extensions": {
        "requestId": "831427d7-686c-49fb-927e-2f1f9d3837d3"
    }
}

## Create advanced transactions
Follow the steps below to create an advanced transaction:

1. Select [chargeCreditCard](https://graphql.braintreepayments.com/reference/#Mutation--chargeCreditCard) mutation method to create advanced transaction as this accepts additional inputs. For additional inputs please refer [inputs](https://graphql.braintreepayments.com/reference/#input_object--) which lists all the creditcard options that are included. Some examples are:
* Passing Billing Address
* Tokenized CVV
* 3DS authentication and so on.

*MutationCodeBlock*

mutation ChargeCreditCard($input: ChargeCreditCardInput!) {
  chargeCreditCard(input: $input) {
    clientMutationId
		transaction {
      id
      legacyId
      createdAt
      paymentMethod {
        customer {
          firstName
          lastName
          phoneNumber
        }
      }
      amount {
        value
        currencyCode
      }
      status
    }
  }
}

*VariableCodeBlock*

{
  "input": {
    "paymentMethodId": "fake-valid-nonce",
    "options": {
      "billingAddress": {
        "addressLine1": "123 Main St",
        "adminArea1": "CA",
        "adminArea2": "San Jose",
        "postalCode": "95086"
      }
    },
    "transaction": {
      "amount": "1.00"
    }
  }
}

*ResponseCodeBlock*

{
  "data": {
    "chargeCreditCard": {
      "clientMutationId": null,
      "transaction": {
        "id": "dHJhbnNhY3Rpb25fbm1idnAwMnA",
        "legacyId": "nmbvp02p",
        "createdAt": "2022-08-04T00:13:22.000000Z",
        "paymentMethod": null,
        "amount": {
          "value": "1.00",
          "currencyCode": "USD"
        },
        "status": "SUBMITTED_FOR_SETTLEMENT"
      }
    }
  },
  "extensions": {
    "requestId": "3008bcc8-2c1d-4f23-909f-7bfa0f91a965"
  }
}

# Vault with Verification
Use [vaultCreditCard](https://graphql.braintreepayments.com/reference/#Mutation--vaultCreditCard) mutation method to verify and vault a credit card. If the verification is successful, the resulting multi-use payment method is vaulted and the status attribute in the response is set to “VERIFIED”.

*MutationCodeBlock*

mutation VaultCreditCard($input: VaultCreditCardInput!) {
  vaultCreditCard(input: $input) {
    paymentMethod {
      id
      usage
      details {
        ... on CreditCardDetails {
          brandCode
          last4
          billingAddress {
            postalCode
          }
        }
      }
    }

    verification {
      id
      legacyId
      paymentMethod {
        id
        createdAt
      }
      status
      processorResponse {
        legacyCode
        message
        cvvResponse
        avsPostalCodeResponse
        avsStreetAddressResponse
      }
      gatewayRejectionReason
      paymentMethodVerificationDetails {
        ... on CreditCardVerificationDetails {
          amount {
            value
            currencyCode
          }
        }
      }
    }
  }
}

*VariableCodeBlock*

{
  "input": {
    "paymentMethodId": "fake-valid-nonce",
    "verification": {
      "amount": "1.00"
    },
    "riskData": {
     	"customerIp": "Chrome",
      "customerIp": "2.4.8.16",
      "deviceData": "Android_12.1.3_CPU_ARM"
    }
  }
}

*ResponseCodeBlock*

{
  "data": {
    "vaultCreditCard": {
      "paymentMethod": {
        "id": "cGF5bWVudG1ldGhvZF9jY19oZjJ3cm1i",
        "usage": "MULTI_USE",
        "details": {
          "brandCode": "VISA",
          "last4": "1881",
          "billingAddress": {
            "postalCode": "94107"
          }
        }
      },
      "verification": {
        "id": "dmVyaWZpY2F0aW9uXzZwZ3JkNDkw",
        "legacyId": "6pgrd490",
        "paymentMethod": {
          "id": "cGF5bWVudG1ldGhvZF9jY19oZjJ3cm1i",
          "createdAt": "2022-08-10T01:18:21.000000Z"
        },
        "status": "VERIFIED",
        "processorResponse": {
          "legacyCode": "1000",
          "message": "Approved",
          "cvvResponse": "MATCHES",
          "avsPostalCodeResponse": "MATCHES",
          "avsStreetAddressResponse": "NOT_PROVIDED"
        },
        "gatewayRejectionReason": null,
        "paymentMethodVerificationDetails": {
          "amount": {
            "value": "1.00",
            "currencyCode": "USD"
          }
        }
      }
    }
  },
  "extensions": {
    "requestId": "a8591622-e331-464c-9a80-60ef068c5052"
  }
}

## Verification Status
Verification method provides two output status:
* Successful verification
* Unsuccessful verification
* Unsuccessful Verification Results (with reasons)

### Successful verification status
If verification is successful, the result will contain a CreditCard response object, which contains a CreditCardVerification response object.

*ResponseCodeBlock*

  "paymentMethodVerificationDetails": {
          "__typename": "CreditCardVerificationDetails",
          "amount": {
            "value": "1.25",
            "currencyCode": "USD"
          }
        }

### Unsuccessful Verification Status
For unsuccessful verification status the user receives a CreditCardVerification response object directly on a customer or PaymentMethod result. This occurs only if:
* A verification ran and it was returned with a status of processor_declined or gateway_rejected
[status](https://developer.paypal.com/braintree/docs/reference/response/credit-card-verification#status) of processor_declined or gateway_rejected

#### Unsuccessful verification results (with Reasons)
Check the [processor_response_code](https://developer.paypal.com/braintree/docs/reference/response/credit-card-verification#processor_response_code) and [processor_response_text](https://developer.paypal.com/braintree/docs/reference/response/credit-card-verification#processor_response_text) for the specific reason that a verification was processor_declined.

## Verifications on sub-merchant accounts
For users using [Braintree Marketplace](https://developer.paypal.com/braintree/docs/guides/braintree-marketplace/overview), verifications cannot be done using sub-merchant accounts. Please refer [Braintree Marketplace Verifications](https://developer.paypal.com/braintree/docs/guides/braintree-marketplace/create#verifications) for more details.

# Reference
For more information refer:
1. [Creating transactions](https://developer.paypal.com/braintree/docs/guides/transactions)
2. [Creating and updating customers](https://developer.paypal.com/braintree/docs/guides/customers)
3. [Creating and updating payment methods](https://developer.paypal.com/braintree/docs/guides/payment-methods)
4. [CreditCardVerification](https://developer.paypal.com/braintree/docs/reference/response/credit-card-verification)
5. [Verifying cards with Hosted Fields](https://developer.paypal.com/braintree/docs/guides/hosted-fields/faq)