On This Page
FILTER BY TAG

Authorize an Apple Pay Payment with Merchant Decryption

The topics in this section show to how to authorize an Apple Pay payment transaction with the
merchant decryption
 implementation of Apple Pay
  • Basic Steps: Authorizing a Payment with Merchant Decryption
  • Fields Required to Authorize a Payment with Merchant Decryption
  • REST Example: Authorize an American Express Payment
  • REST Example: Authorize a Discover Payment
  • REST Example: Authorize a JCB Payment
  • REST Example: Authorize a mada Payment
  • REST Example: Authorize a Mastercard Payment
  • REST Example: Authorize a Visa Payment

Basic Steps: Authorizing a Payment with Merchant Decryption

  1. Follow these steps to request an Apple Pay payment authorization with merchant decryption:
  2. Create the request message with the required
    REST
     API fields.
  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 .

Fields Required to Authorize a Payment with Merchant Decryption

As a best practice, include these
REST API
 fields in your request for an authorization 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
.
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.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: Authorize an American Express Payment with Merchant Decryption

American Express Auth Request
{ 
  "clientReferenceInformation": {
    "code": "TC_1231223"
  },
  "processingInformation": {
    "commerceIndicator": "internet",
    "paymentSolution": "001"
  },
  "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"
    }
  }
}
Response to a Successful Request
{
  "_links": {
    "authReversal": {
      "method": "POST",
      "href": "/pts/v2/payments/7359621903916966603954/reversals"
    },
    "self": {
      "method": "GET",
      "href": "/pts/v2/payments/7359621903916966603954"
    },
    "capture": {
      "method": "POST",
      "href": "/pts/v2/payments/7359621903916966603954/captures"
    }
  },
  "clientReferenceInformation": {
    "code": "TC_1231223"
  },
  "id": "7359621903916966603954",
  "orderInformation": {
    "amountDetails": {
      "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": "918032",
    "approvalCode": "831000",
    "merchantAdvice": {
      "code": "01",
      "codeRaw": "M001"
    },
    "responseDetails": "ABC",
    "networkTransactionId": "016153570198200",
    "retrievalReferenceNumber": "500303918032",
    "consumerAuthenticationResponse": {
      "code": "2",
      "codeRaw": "2"
    },
    "transactionId": "016153570198200",
    "responseCode": "00",
    "avs": {
      "code": "Y",
      "codeRaw": "Y"
    }
  },
  "reconciliationId": "7359621903916966603954",
  "status": "AUTHORIZED",
  "submitTimeUtc": "2025-01-04T03:43:10Z"
}

REST Example: Authorize a Discover Payment with Merchant Decryption

Discover Auth Request
{ 
  "clientReferenceInformation": {
    "code": "TC_1231223"
  },
  "processingInformation": {
    "commerceIndicator": "internet",
    "paymentSolution": "001"
  },
  "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"
    }
  }
}
Response to a Successful Request
{
  "_links": {
    "authReversal": {
      "method": "POST",
      "href": "/pts/v2/payments/7359621903916966603954/reversals"
    },
    "self": {
      "method": "GET",
      "href": "/pts/v2/payments/7359621903916966603954"
    },
    "capture": {
      "method": "POST",
      "href": "/pts/v2/payments/7359621903916966603954/captures"
    }
  },
  "clientReferenceInformation": {
    "code": "TC_1231223"
  },
  "id": "7359621903916966603954",
  "orderInformation": {
    "amountDetails": {
      "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": "918032",
    "approvalCode": "831000",
    "merchantAdvice": {
      "code": "01",
      "codeRaw": "M001"
    },
    "responseDetails": "ABC",
    "networkTransactionId": "016153570198200",
    "retrievalReferenceNumber": "500303918032",
    "consumerAuthenticationResponse": {
      "code": "2",
      "codeRaw": "2"
    },
    "transactionId": "016153570198200",
    "responseCode": "00",
    "avs": {
      "code": "Y",
      "codeRaw": "Y"
    }
  },
  "reconciliationId": "7359621903916966603954",
  "status": "AUTHORIZED",
  "submitTimeUtc": "2025-01-04T03:43:10Z"
}

REST Example: Authorize a JCB Payment with Merchant Decryption

JCB Auth Request
{ 
  "clientReferenceInformation": {
    "code": "TC_1231223"
  },
  "processingInformation": {
    "commerceIndicator": "internet",
    "paymentSolution": "001"
  },
  "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"
    }
  }
}
Response to a Successful Request
{
  "_links": {
    "authReversal": {
      "method": "POST",
      "href": "/pts/v2/payments/7359621903916966603954/reversals"
    },
    "self": {
      "method": "GET",
      "href": "/pts/v2/payments/7359621903916966603954"
    },
    "capture": {
      "method": "POST",
      "href": "/pts/v2/payments/7359621903916966603954/captures"
    }
  },
  "clientReferenceInformation": {
    "code": "TC_1231223"
  },
  "id": "7359621903916966603954",
  "orderInformation": {
    "amountDetails": {
      "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": "918032",
    "approvalCode": "831000",
    "merchantAdvice": {
      "code": "01",
      "codeRaw": "M001"
    },
    "responseDetails": "ABC",
    "networkTransactionId": "016153570198200",
    "retrievalReferenceNumber": "500303918032",
    "consumerAuthenticationResponse": {
      "code": "2",
      "codeRaw": "2"
    },
    "transactionId": "016153570198200",
    "responseCode": "00",
    "avs": {
      "code": "Y",
      "codeRaw": "Y"
    }
  },
  "reconciliationId": "7359621903916966603954",
  "status": "AUTHORIZED",
  "submitTimeUtc": "2025-01-04T03:43:10Z"
}

REST Example: Authorize a mada Payment with Merchant Decryption

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 authorize an Apple Pay payment with 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 Auth Request
{ 
  "clientReferenceInformation": {
    "code": "TC_1231223"
  },
  "processingInformation": {
    "commerceIndicator": "internet",
    "paymentSolution": "001"
  },
  "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": {
    "authReversal": {
      "method": "POST",
      "href": "/pts/v2/payments/7359621903916966603954/reversals"
    },
    "self": {
      "method": "GET",
      "href": "/pts/v2/payments/7359621903916966603954"
    },
    "capture": {
      "method": "POST",
      "href": "/pts/v2/payments/7359621903916966603954/captures"
    }
  },
  "clientReferenceInformation": {
    "code": "TC_1231223"
  },
  "id": "7359621903916966603954",
  "orderInformation": {
    "amountDetails": {
      "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": "918032",
    "approvalCode": "831000",
    "merchantAdvice": {
      "code": "01",
      "codeRaw": "M001"
    },
    "responseDetails": "ABC",
    "networkTransactionId": "016153570198200",
    "retrievalReferenceNumber": "500303918032",
    "consumerAuthenticationResponse": {
      "code": "2",
      "codeRaw": "2"
    },
    "transactionId": "016153570198200",
    "responseCode": "00",
    "avs": {
      "code": "Y",
      "codeRaw": "Y"
    }
  },
  "reconciliationId": "7359621903916966603954",
  "status": "AUTHORIZED",
  "submitTimeUtc": "2025-01-04T03:43:10Z"
}

REST Example: Authorize a Mastercard Payment with Merchant Decryption

Mastercard Auth Request
{ 
  "clientReferenceInformation": {
    "code": "TC_1231223"
  },
  "processingInformation": {
    "commerceIndicator": "internet",
    "paymentSolution": "001"
  },
  "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"
    }
  },
  "consumerAuthenticationInformation": {
    "ucafAuthenticationData": "ABCDEFabcdefABCDEFabcdef0987654321234567",
    "ucafCollectionIndicator": "2"
   }
}
Response to a Successful Request
{
  "_links": {
    "authReversal": {
      "method": "POST",
      "href": "/pts/v2/payments/7359621903916966603954/reversals"
    },
    "self": {
      "method": "GET",
      "href": "/pts/v2/payments/7359621903916966603954"
    },
    "capture": {
      "method": "POST",
      "href": "/pts/v2/payments/7359621903916966603954/captures"
    }
  },
  "clientReferenceInformation": {
    "code": "TC_1231223"
  },
  "id": "7359621903916966603954",
  "orderInformation": {
    "amountDetails": {
      "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": "918032",
    "approvalCode": "831000",
    "merchantAdvice": {
      "code": "01",
      "codeRaw": "M001"
    },
    "responseDetails": "ABC",
    "networkTransactionId": "016153570198200",
    "retrievalReferenceNumber": "500303918032",
    "consumerAuthenticationResponse": {
      "code": "2",
      "codeRaw": "2"
    },
    "transactionId": "016153570198200",
    "responseCode": "00",
    "avs": {
      "code": "Y",
      "codeRaw": "Y"
    }
  },
  "reconciliationId": "7359621903916966603954",
  "status": "AUTHORIZED",
  "submitTimeUtc": "2025-01-04T03:43:10Z"
}

REST Example: Authorize a Visa Payment with Merchant Decryption

Visa Auth Request
{ 
  "clientReferenceInformation": {
    "code": "TC_1231223"
  },
  "processingInformation": {
    "commerceIndicator": "internet",
    "paymentSolution": "001"
  },
  "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"
    }
  }
}
Response to a Successful Request
{
  "_links": {
    "authReversal": {
      "method": "POST",
      "href": "/pts/v2/payments/7359621903916966603954/reversals"
    },
    "self": {
      "method": "GET",
      "href": "/pts/v2/payments/7359621903916966603954"
    },
    "capture": {
      "method": "POST",
      "href": "/pts/v2/payments/7359621903916966603954/captures"
    }
  },
  "clientReferenceInformation": {
    "code": "TC_1231223"
  },
  "id": "7359621903916966603954",
  "orderInformation": {
    "amountDetails": {
      "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": "918032",
    "approvalCode": "831000",
    "merchantAdvice": {
      "code": "01",
      "codeRaw": "M001"
    },
    "responseDetails": "ABC",
    "networkTransactionId": "016153570198200",
    "retrievalReferenceNumber": "500303918032",
    "consumerAuthenticationResponse": {
      "code": "2",
      "codeRaw": "2"
    },
    "transactionId": "016153570198200",
    "responseCode": "00",
    "avs": {
      "code": "Y",
      "codeRaw": "Y"
    }
  },
  "reconciliationId": "7359621903916966603954",
  "status": "AUTHORIZED",
  "submitTimeUtc": "2025-01-04T03:43:10Z"
}
RELATED TO THIS PAGE