Process an Apple Pay Sale with Merchant Decryption {#applepay-txn-sale-merch-ex}
================================================================================

A sale bundles an authorization and capture in a single transaction. Request the authorization and capture at the same time. The authorization and capture amounts must be the same. The `REST` API message for a sale request is the same as the message for an authorization request, except that the sale request message must set the processingInformation.capture field to `true`.  
The topics in this section show to how to process an Apple Pay sale with the *merchant decryption* implementation of Apple Pay:

* Basic Steps: Processing a Sale with Merchant Decryption
* Fields Required to Process a Sale with Merchant Decryption
* REST Example: Process an American Express Sale
* REST Example: Process a Discover Sale
* REST Example: Process a JCB Sale
* REST Example: Processe a mada Sale
* REST Example: Process a Mastercard Sale
* REST Example: Process a Visa Sale

Basic Steps: Processing a Sale with Merchant Decryption {#applepay-txn-sale-merch-ex-rest-steps}
================================================================================================

1. Follow these steps to process an Apple Pay sale transaction with merchant decryption:

2. Create the request message with the required `REST` API fields.

   * Use the API fields listed in [Fields Required to Process a Sale with Merchant Decryption](/docs/bofa/en-us/apple-pay/developer/gpx/rest/applepay/applepay-txns-intro/applepay-txn-sale-merch-ex/applepay-txn-sale-merch-ex-rest-fields.md "").

   * Refer to the example for your payment card type:

     * [REST Example: Process an American Express Sale with Merchant Decryption](/docs/bofa/en-us/apple-pay/developer/gpx/rest/applepay/applepay-txns-intro/applepay-txn-sale-merch-ex/applepay-txn-sale-merch-ex-rest-code-amex.md "")
     * [REST Example: Process a Discover Sale with Merchant Decryption](/docs/bofa/en-us/apple-pay/developer/gpx/rest/applepay/applepay-txns-intro/applepay-txn-sale-merch-ex/applepay-txn-sale-merch-ex-rest-code-discover.md "")
     * [REST Example: Process a JCB Sale with Merchant Decryption](/docs/bofa/en-us/apple-pay/developer/gpx/rest/applepay/applepay-txns-intro/applepay-txn-sale-merch-ex/applepay-txn-sale-merch-ex-rest-code-jcb.md "")
     * [REST Example: Process a mada Sale with Merchant Decryption](/docs/bofa/en-us/apple-pay/developer/gpx/rest/applepay/applepay-txns-intro/applepay-txn-sale-merch-ex/applepay-txn-sale-merch-ex-rest-code-mada.md "")
     * [REST Example: Process a Mastercard Sale with Merchant Decryption](/docs/bofa/en-us/apple-pay/developer/gpx/rest/applepay/applepay-txns-intro/applepay-txn-sale-merch-ex/applepay-txn-sale-merch-ex-rest-code-mc.md "")
     * [REST Example: Process a Visa Sale with Merchant Decryption](/docs/bofa/en-us/apple-pay/developer/gpx/rest/applepay/applepay-txns-intro/applepay-txn-sale-merch-ex/applepay-txn-sale-merch-ex-rest-code-visa.md "")

     > IMPORTANT In these code examples, any test card numbers that contain zeroes are formatted with Xs replacing the zeroes. When you test using one of these reformatted card numbers, replace each X with a 0 (zero).

3. Send the message to one of these endpoints:

   * Production: `POST ``https://api.merchant-services.bankofamerica.com``/pts/v2/payments`
   * Test: `POST ``https://apitest.merchant-services.bankofamerica.com``/pts/v2/payments`
4. Verify the response messages to make sure that the request was successful.

   #### ADDITIONAL INFORMATION

A 200-level HTTP response code indicates success. See the [Transaction Response Codes](https://developer.merchant.services.bankofamerica.com/api/reference/response-codes.md "").

Fields Required to Process a Sale with Merchant Decryption {#applepay-txn-sale-merch-ex-rest-fields}
====================================================================================================

As a best practice, include these REST API fields in your request for a combined authorization and capture (sale) transaction with the `Bank of America` decryption implementation of Apple Pay.  
Depending on your processor, your geographic location, and whether the relaxed address verification system (RAVS) is enabled for your account, some of these fields might not be required. It is your responsibility to determine whether an API field can be omitted from the transaction you are requesting. For information about the relaxed requirements for address data and expiration dates in payment transactions, see the [Payments Developer Guide](https://developer.merchant.services.bankofamerica.com/docs/bofa/en-us/payments/developer/ctv/rest/payments/payments-intro.md "").

clientReferenceInformation.code
:

consumerAuthenticationInformation.ucafAuthenticationData
:
Universal cardholder authentication field (UCAF) data. For Apple Pay, this field is available (but optional) only for merchant decryption of Mastercard transactions on `FDC Compass` and `Bank of America Gateway` processors.

consumerAuthenticationInformation.ucafCollectionIndicator
:
Universal cardholder authentication field (UCAF) collection indicator used for Mastercard Identity Check. For Apple Pay, this field is available and required only for merchant decryption of Mastercard transactions on the `Bank of America Gateway` processor.
:
Set the value to `2`.

orderInformation.amountDetails.currency
:

orderInformation.amountDetails.totalAmount
:

orderInformation.billTo.address1
:

orderInformation.billTo.administrativeArea
:

orderInformation.billTo.country
:

orderInformation.billTo.email
:

orderInformation.billTo.firstName
:

orderInformation.billTo.lastName
:

orderInformation.billTo.locality
:

orderInformation.billTo.postalCode
:

paymentInformation.tokenizedCard.cryptogram
:
Token authentication verification value cryptogram.
:
The value for this field must be a 28-character, Base64-encoded string (the encoding method for Apple Pay transactions).

paymentInformation.tokenizedCard.expirationMonth
:
Set the value to month in which the token expires. Format: `MM`  
Possible values: `01` through `12`.

paymentInformation.tokenizedCard.expirationYear
:
Set the value to the year in which the token expires. Format: `yyyy`.

paymentInformation.tokenizedCard.number
:
Set the value to customer's payment network token value that contains the customer's credit card number.

paymentInformation.tokenizedCard.transactionType
:
For `Elavon Americas`, `FDC Compass`, `Bank of America Gateway`, and `GPX` processors, set this field to the value that indicates the type of transaction that provided the payment network token data. Possible values:

    * `1`: In-app transaction.
    * `2`: Near-field communication (NFC) transaction. The customer's mobile device provided the token data for a contactless EMV transaction.
    * `3`: A transaction using stored customer credentials on `Bank of America Gateway`, whether for merchant-initiated transactions (MITs) or customer-initiated transactions (CITs).

:
> IMPORTANT This value does not specify the token service provider. It specifies the entity that provided you with information about the token.

paymentInformation.tokenizedCard.type
:
Three-digit value that indicates the card type. Possible values:

    * `001`: Visa
    * `002`: Mastercard

processingInformation.capture
:
Set the value to `true` to include a capture with the authorization.

processingInformation.commerceIndicator
:
Type of transaction. Some payment card companies use this information when determining discount rates. Possible values:

    * `aesk`: American Express SafeKey authentication.
    * `dipb`: Discover card type.
    * `internet`: Default value for authorizations. E-commerce order placed from a website.
    * `js`: JCB J/Secure authentication.
    * `mada`: mada authentication.
    * `spa`: Mastercard Identity Check authentication.
When the transaction type field is set to this value, you must also include the consumerAuthenticationInformation. ucafCollectionIndicator field with the value set to `2`.
    * `vbv`: Visa Secure authentication

:
For a transaction on a mada co-badged Mastercard, set the value to `mada` or `spa`.
:
For a transaction on a mada co-badged Visa card, set the value to `mada` or `vbv`

processingInformation.paymentSolution
:
Set the value to `001` to identify Apple Pay as the digital payment solution.

REST Example: Process an American Express Sale with Merchant Decryption {#applepay-txn-sale-merch-ex-rest-code-amex}
====================================================================================================================

American Express Sale Request

```
{ 
  "clientReferenceInformation": {
    "code": "TC_1231223"
  },
  "processingInformation": {
    "commerceIndicator": "internet",
    "paymentSolution": "001",
    "capture": true
  },
  "paymentInformation": {
    "tokenizedCard": {
      "number": "37828224631XXX5",
      "expirationMonth": "12",
      "expirationYear": "2031",
      "cryptogram": "AceY+igABPs3jdwNaDg3MAACAAA=",
      "transactionType": "1",
      "type": "003"
    }
  },
  "orderInformation": {
    "amountDetails": {
      "totalAmount": "10",
      "currency": "USD"
    },
    "billTo": {
      "firstName": "John",
      "lastName": "Doe",
      "address1": "901 Metro Center Blvd",
      "locality": "Foster City",
      "administrativeArea": "CA",
      "postalCode": "94404",
      "country": "US",
      "email": "test@bankofamerica.com.com"
    }
  }
}
```

Response to a Successful Request

```
{
  "_links": {
    "void": {
      "method": "POST",
      "href": "/pts/v2/payments/7359627932726161403954/voids"
    },
    "self": {
      "method": "GET",
      "href": "/pts/v2/payments/7359627932726161403954"
    }
  },
  "clientReferenceInformation": {
    "code": "TC_1231223"
  },
  "id": "7359627932726161403954",
  "orderInformation": {
    "amountDetails": {
      "totalAmount": "10.00",
      "authorizedAmount": "10.00",
      "currency": "USD"
    }
  },
  "paymentAccountInformation": {
    "card": {
      "type": "003"
    }
  },
  "paymentInformation": {
    "tokenizedCard": {
      "expirationYear": "2031",
      "prefix": "411111",
      "expirationMonth": "12",
      "suffix": "1111",
      "type": "003"
    },
    "card": {
      "type": "003"
    }
  },
  "processingInformation": {
    "paymentSolution": "001"
  },
  "processorInformation": {
    "systemTraceAuditNumber": "417802",
    "approvalCode": "831000",
    "merchantAdvice": {
      "code": "01",
      "codeRaw": "M001"
    },
    "responseDetails": "ABC",
    "networkTransactionId": "016153570198200",
    "retrievalReferenceNumber": "500303417802",
    "consumerAuthenticationResponse": {
      "code": "2",
      "codeRaw": "2"
    },
    "transactionId": "016153570198200",
    "responseCode": "00",
    "avs": {
      "code": "Y",
      "codeRaw": "Y"
    }
  },
  "reconciliationId": "7359627932726161403954",
  "status": "AUTHORIZED",
  "submitTimeUtc": "2025-01-04T03:53:13Z"
}
```

REST Example: Process a Discover Sale with Merchant Decryption {#applepay-txn-sale-merch-ex-rest-code-discover}
===============================================================================================================

Discover Sale Request

```
{ 
  "clientReferenceInformation": {
    "code": "TC_1231223"
  },
  "processingInformation": {
    "commerceIndicator": "internet",
    "paymentSolution": "001",
    "capture": true
  },
  "paymentInformation": {
    "tokenizedCard": {
      "number": "6X11111111111117",
      "expirationMonth": "12",
      "expirationYear": "2031",
      "cryptogram": "AceY+igABPs3jdwNaDg3MAACAAA=",
      "transactionType": "1",
      "type": "004"
    }
  },
  "orderInformation": {
    "amountDetails": {
      "totalAmount": "10",
      "currency": "USD"
    },
    "billTo": {
      "firstName": "John",
      "lastName": "Doe",
      "address1": "901 Metro Center Blvd",
      "locality": "Foster City",
      "administrativeArea": "CA",
      "postalCode": "94404",
      "country": "US",
      "email": "test@bankofamerica.com.com"
    }
  }
}
```

Response to a Successful Request

```
{
  "_links": {
    "void": {
      "method": "POST",
      "href": "/pts/v2/payments/7359627932726161403954/voids"
    },
    "self": {
      "method": "GET",
      "href": "/pts/v2/payments/7359627932726161403954"
    }
  },
  "clientReferenceInformation": {
    "code": "TC_1231223"
  },
  "id": "7359627932726161403954",
  "orderInformation": {
    "amountDetails": {
      "totalAmount": "10.00",
      "authorizedAmount": "10.00",
      "currency": "USD"
    }
  },
  "paymentAccountInformation": {
    "card": {
      "type": "004"
    }
  },
  "paymentInformation": {
    "tokenizedCard": {
      "expirationYear": "2031",
      "prefix": "411111",
      "expirationMonth": "12",
      "suffix": "1111",
      "type": "004"
    },
    "card": {
      "type": "004"
    }
  },
  "processingInformation": {
    "paymentSolution": "001"
  },
  "processorInformation": {
    "systemTraceAuditNumber": "417802",
    "approvalCode": "831000",
    "merchantAdvice": {
      "code": "01",
      "codeRaw": "M001"
    },
    "responseDetails": "ABC",
    "networkTransactionId": "016153570198200",
    "retrievalReferenceNumber": "500303417802",
    "consumerAuthenticationResponse": {
      "code": "2",
      "codeRaw": "2"
    },
    "transactionId": "016153570198200",
    "responseCode": "00",
    "avs": {
      "code": "Y",
      "codeRaw": "Y"
    }
  },
  "reconciliationId": "7359627932726161403954",
  "status": "AUTHORIZED",
  "submitTimeUtc": "2025-01-04T03:53:13Z"
}
```

REST Example: Process a JCB Sale with Merchant Decryption {#applepay-txn-sale-merch-ex-rest-code-jcb}
=====================================================================================================

JCB Sale Request

```
{ 
  "clientReferenceInformation": {
    "code": "TC_1231223"
  },
  "processingInformation": {
    "commerceIndicator": "internet",
    "paymentSolution": "001",
    "capture": true
  },
  "paymentInformation": {
    "tokenizedCard": {
      "number": "3566111111111113",
      "expirationMonth": "12",
      "expirationYear": "2031",
      "cryptogram": "AceY+igABPs3jdwNaDg3MAACAAA=",
      "transactionType": "1",
      "type": "007"
    }
  },
  "orderInformation": {
    "amountDetails": {
      "totalAmount": "10",
      "currency": "USD"
    },
    "billTo": {
      "firstName": "John",
      "lastName": "Doe",
      "address1": "901 Metro Center Blvd",
      "locality": "Foster City",
      "administrativeArea": "CA",
      "postalCode": "94404",
      "country": "US",
      "email": "test@bankofamerica.com.com"
    }
  }
}
```

Response to a Successful Request

```
{
  "_links": {
    "void": {
      "method": "POST",
      "href": "/pts/v2/payments/7359627932726161403954/voids"
    },
    "self": {
      "method": "GET",
      "href": "/pts/v2/payments/7359627932726161403954"
    }
  },
  "clientReferenceInformation": {
    "code": "TC_1231223"
  },
  "id": "7359627932726161403954",
  "orderInformation": {
    "amountDetails": {
      "totalAmount": "10.00",
      "authorizedAmount": "10.00",
      "currency": "USD"
    }
  },
  "paymentAccountInformation": {
    "card": {
      "type": "007"
    }
  },
  "paymentInformation": {
    "tokenizedCard": {
      "expirationYear": "2031",
      "prefix": "411111",
      "expirationMonth": "12",
      "suffix": "1111",
      "type": "007"
    },
    "card": {
      "type": "007"
    }
  },
  "processingInformation": {
    "paymentSolution": "001"
  },
  "processorInformation": {
    "systemTraceAuditNumber": "417802",
    "approvalCode": "831000",
    "merchantAdvice": {
      "code": "01",
      "codeRaw": "M001"
    },
    "responseDetails": "ABC",
    "networkTransactionId": "016153570198200",
    "retrievalReferenceNumber": "500303417802",
    "consumerAuthenticationResponse": {
      "code": "2",
      "codeRaw": "2"
    },
    "transactionId": "016153570198200",
    "responseCode": "00",
    "avs": {
      "code": "Y",
      "codeRaw": "Y"
    }
  },
  "reconciliationId": "7359627932726161403954",
  "status": "AUTHORIZED",
  "submitTimeUtc": "2025-01-04T03:53:13Z"
}
```

REST Example: Process a mada Sale with Merchant Decryption {#applepay-txn-sale-merch-ex-rest-code-mada}
=======================================================================================================

Apple Pay supports mada Pay mobile app transactions with `Bank of America Gateway` only and only for these payment cards issued in the Kingdom of Saudi Arabia:

* mada
* Mastercard co-badged with mada
* Visa co-badged with mada  
  To process an Apple Pay sale on the mada Pay mobile app---whether for a mada card or for a mada co-badged Mastercard or Visa card---specify the mada card type (value `060`) in the paymentInformation.tokenizedCard.type REST API field. For more information, see Co-Badged Cards in the Payments Developer Guide for `Bank of America Gateway`.  
  mada Sale Request

```
{ 
  "clientReferenceInformation": {
    "code": "TC_1231223"
  },
  "processingInformation": {
    "commerceIndicator": "internet",
    "paymentSolution": "001",
    "capture": true
  },
  "paymentInformation": {
    "tokenizedCard": {
      "number": "4111111111111111",
      "expirationMonth": "12",
      "expirationYear": "2031",
      "cryptogram": "AceY+igABPs3jdwNaDg3MAACAAA=",
      "transactionType": "1",
      "type": "060"
    }
  },
  "orderInformation": {
    "amountDetails": {
      "totalAmount": "10",
      "currency": "USD"
    },
    "billTo": {
      "firstName": "John",
      "lastName": "Doe",
      "address1": "901 Metro Center Blvd",
      "locality": "Foster City",
      "administrativeArea": "CA",
      "postalCode": "94404",
      "country": "US",
      "email": "test@bankofamerica.com"
    }
  }
}
```

Response to a Successful Request

```
{
  "_links": {
    "void": {
      "method": "POST",
      "href": "/pts/v2/payments/7359627932726161403954/voids"
    },
    "self": {
      "method": "GET",
      "href": "/pts/v2/payments/7359627932726161403954"
    }
  },
  "clientReferenceInformation": {
    "code": "TC_1231223"
  },
  "id": "7359627932726161403954",
  "orderInformation": {
    "amountDetails": {
      "totalAmount": "10.00",
      "authorizedAmount": "10.00",
      "currency": "USD"
    }
  },
  "paymentAccountInformation": {
    "card": {
      "type": "060"
    }
  },
  "paymentInformation": {
    "tokenizedCard": {
      "expirationYear": "2031",
      "prefix": "411111",
      "expirationMonth": "12",
      "suffix": "1111",
      "type": "060"
    },
    "card": {
      "type": "060"
    }
  },
  "processingInformation": {
    "paymentSolution": "001"
  },
  "processorInformation": {
    "systemTraceAuditNumber": "417802",
    "approvalCode": "831000",
    "merchantAdvice": {
      "code": "01",
      "codeRaw": "M001"
    },
    "responseDetails": "ABC",
    "networkTransactionId": "016153570198200",
    "retrievalReferenceNumber": "500303417802",
    "consumerAuthenticationResponse": {
      "code": "2",
      "codeRaw": "2"
    },
    "transactionId": "016153570198200",
    "responseCode": "00",
    "avs": {
      "code": "Y",
      "codeRaw": "Y"
    }
  },
  "reconciliationId": "7359627932726161403954",
  "status": "AUTHORIZED",
  "submitTimeUtc": "2025-01-04T03:53:13Z"
}
```

REST Example: Process a Mastercard Sale with Merchant Decryption {#applepay-txn-sale-merch-ex-rest-code-mc}
===========================================================================================================

Mastercard Sale Request

```
{ 
  "clientReferenceInformation": {
    "code": "TC_1231223"
  },
  "processingInformation": {
    "commerceIndicator": "internet",
    "paymentSolution": "001",
    "capture": true
  },
  "paymentInformation": {
    "tokenizedCard": {
      "number": "5555555555554444",
      "expirationMonth": "12",
      "expirationYear": "2031",
      "cryptogram": "AceY+igABPs3jdwNaDg3MAACAAA=",
      "transactionType": "1",
      "type": "002"
    }
  },
  "orderInformation": {
    "amountDetails": {
      "totalAmount": "10",
      "currency": "USD"
    },
    "billTo": {
      "firstName": "John",
      "lastName": "Doe",
      "address1": "901 Metro Center Blvd",
      "locality": "Foster City",
      "administrativeArea": "CA",
      "postalCode": "94404",
      "country": "US",
      "email": "test@bankofamerica.com.com"
    }
  },
  "consumerAuthenticationInformation": {
    "ucafAuthenticationData": "ABCDEFabcdefABCDEFabcdef0987654321234567",
    "ucafCollectionIndicator": "2"
  }
}
```

Response to a Successful Request

```
{
  "_links": {
    "void": {
      "method": "POST",
      "href": "/pts/v2/payments/7359627932726161403954/voids"
    },
    "self": {
      "method": "GET",
      "href": "/pts/v2/payments/7359627932726161403954"
    }
  },
  "clientReferenceInformation": {
    "code": "TC_1231223"
  },
  "id": "7359627932726161403954",
  "orderInformation": {
    "amountDetails": {
      "totalAmount": "10.00",
      "authorizedAmount": "10.00",
      "currency": "USD"
    }
  },
  "paymentAccountInformation": {
    "card": {
      "type": "002"
    }
  },
  "paymentInformation": {
    "tokenizedCard": {
      "expirationYear": "2031",
      "prefix": "411111",
      "expirationMonth": "12",
      "suffix": "1111",
      "type": "002"
    },
    "card": {
      "type": "002"
    }
  },
  "processingInformation": {
    "paymentSolution": "001"
  },
  "processorInformation": {
    "systemTraceAuditNumber": "417802",
    "approvalCode": "831000",
    "merchantAdvice": {
      "code": "01",
      "codeRaw": "M001"
    },
    "responseDetails": "ABC",
    "networkTransactionId": "016153570198200",
    "retrievalReferenceNumber": "500303417802",
    "consumerAuthenticationResponse": {
      "code": "2",
      "codeRaw": "2"
    },
    "transactionId": "016153570198200",
    "responseCode": "00",
    "avs": {
      "code": "Y",
      "codeRaw": "Y"
    }
  },
  "reconciliationId": "7359627932726161403954",
  "status": "AUTHORIZED",
  "submitTimeUtc": "2025-01-04T03:53:13Z"
}
```

REST Example: Process a Visa Sale with Merchant Decryption {#applepay-txn-sale-merch-ex-rest-code-visa}
=======================================================================================================

Visa Sale Request

```
{ 
  "clientReferenceInformation": {
    "code": "TC_1231223"
  },
  "processingInformation": {
    "commerceIndicator": "internet",
    "paymentSolution": "001",
    "capture": true
  },
  "paymentInformation": {
    "tokenizedCard": {
      "number": "4111111111111111",
      "expirationMonth": "12",
      "expirationYear": "2031",
      "cryptogram": "AceY+igABPs3jdwNaDg3MAACAAA=",
      "transactionType": "1",
      "type": "001"
    }
  },
  "orderInformation": {
    "amountDetails": {
      "totalAmount": "10",
      "currency": "USD"
    },
    "billTo": {
      "firstName": "John",
      "lastName": "Doe",
      "address1": "901 Metro Center Blvd",
      "locality": "Foster City",
      "administrativeArea": "CA",
      "postalCode": "94404",
      "country": "US",
      "email": "test@bankofamerica.com.com"
    }
  }
}
```

Response to a Successful Request

```
{
  "_links": {
    "void": {
      "method": "POST",
      "href": "/pts/v2/payments/7359627932726161403954/voids"
    },
    "self": {
      "method": "GET",
      "href": "/pts/v2/payments/7359627932726161403954"
    }
  },
  "clientReferenceInformation": {
    "code": "TC_1231223"
  },
  "id": "7359627932726161403954",
  "orderInformation": {
    "amountDetails": {
      "totalAmount": "10.00",
      "authorizedAmount": "10.00",
      "currency": "USD"
    }
  },
  "paymentAccountInformation": {
    "card": {
      "type": "001"
    }
  },
  "paymentInformation": {
    "tokenizedCard": {
      "expirationYear": "2031",
      "prefix": "411111",
      "expirationMonth": "12",
      "suffix": "1111",
      "type": "001"
    },
    "card": {
      "type": "001"
    }
  },
  "processingInformation": {
    "paymentSolution": "001"
  },
  "processorInformation": {
    "systemTraceAuditNumber": "417802",
    "approvalCode": "831000",
    "merchantAdvice": {
      "code": "01",
      "codeRaw": "M001"
    },
    "responseDetails": "ABC",
    "networkTransactionId": "016153570198200",
    "retrievalReferenceNumber": "500303417802",
    "consumerAuthenticationResponse": {
      "code": "2",
      "codeRaw": "2"
    },
    "transactionId": "016153570198200",
    "responseCode": "00",
    "avs": {
      "code": "Y",
      "codeRaw": "Y"
    }
  },
  "reconciliationId": "7359627932726161403954",
  "status": "AUTHORIZED",
  "submitTimeUtc": "2025-01-04T03:53:13Z"
}
```