API Overview

Payments Developer Guide
- Recent Revisions to This Document

Introduction to Payments
- Financial Institutions and Payment Networks
  - Merchant Financial Institutions (Acquirers)
  - Customer Financial Institutions (Issuers)
  - Payment Networks
  - Payment Processors
- Card Types
  - Credit Cards
  - Debit Cards
- Transaction Types
  - Card-Not-Present Transactions
  - Authorizations with Card Verification Numbers
    - CVN Locations and Terminology
  - Token Management Service
- Payment Services
  - Authorizations
    - Micropayment Authorizations
    - Online Authorizations
    - Offline Authorizations
    - Incremental Authorizations
      - Scenario for the Incremental Authorization Service
    - Pre-Authorizations
    - Payment Network Token Authorizations
    - Authorization Workflow
  - Sales
    - Dual-Message Processing
      - Partial Authorizations
    - Single-Message Processing
  - Authorization Reversals
  - Captures
    - Capture Workflow
  - Credits
    - Credit Workflow
  - Voids
- Payment Features
  - Debit and Prepaid Card Payments
  - Mastercard Payment of Winnings Stand-Alone Credits
  - Payer Authentication
  - Relaxed Requirements for Address Data and Expiration Date in Payment Transactions
  - Introduction to Credentialed Transactions
  - Token Management Service
- Testing the Payment Services
  - Requirements for Testing
  - Test Card Numbers
  - Using Amounts to Simulate Errors
  - Test American Express Card Verification

Standard Payment Processing
- Additional Resources for Processing Payments
- Basic Authorizations
  - Declined Authorizations
  - Required Fields for Processing a Basic Authorization
  - REST Interactive Example: Processing a Basic Authorization
  - REST Example: Processing a Basic Authorization
- Authorizations with Line Items
  - Required Fields for Processing an Authorization with Line Items
  - REST Example: Processing an Authorization with Line Items
- Authorizations with Payment Network Tokens
  - Required Fields for Authorizations with Payment Network Tokens
  - Optional Fields for Authorizations with Payment Network Tokens
  - REST Example: Authorizations with Payment Network Tokens
- Authorizations with a Card Verification Number
  - Required Fields for Processing an Authorization with a Card Verification Number
  - Optional Fields for Processing an Authorization with a Card Verification Number
  - REST Example: Processing an Authorization with a Card Verification Number
- Marketplace Authorizations with Foreign Retailers
  - Required Fields for Processing a Marketplace Authorization with a Foreign Retailer
  - REST Example: Processing an Marketplace Authorization with a Foreign Retailer
- Authorizations with Strong Customer Authentication Exemption
  - Required Fields for Processing an Authorization with an SCA Exemption
  - REST Example: Processing an Authorization with an SCA Exemption for Low-Value Transactions
- Zero Amount Authorizations
  - Required Fields for Processing a Zero Amount Authorization
  - REST Example: Processing a Zero Amount Authorization
- Pre-Authorizations
  - Required Fields for a Pre-Authorization
  - REST Example: Processing a Pre-Authorization
- Final Authorization Indicator
  - Requirements for Final Authorizations
  - Pre-Authorizations
  - Unmarked Authorizations
    - Requirements for Unmarked Authorizations
  - Undefined Authorizations
    - Requirements for Undefined Authorizations
  - Required Fields for Final Authorizations
  - REST Example: Final Authorizations
- Authorization Reversal
  - Required Fields for Processing an Authorization Reversal
  - REST Example: Processing an Authorization Reversal
- Sales
  - Required Fields for Processing a Sale
  - REST Example: Processing a Sale
- Sales with Payment Network Tokens
  - Required Fields for Sales with Payment Network Tokens
  - Optional Fields for Sales with Payment Network Tokens
  - REST Example: Sales with Payment Network Tokens
- Captures
  - Required Fields for Capturing an Authorization
  - REST Example: Capturing an Authorization
- Marketplace Captures with Foreign Retailers
  - Required Fields for Capturing an Authorization with a Foreign Retailer
  - REST Example: Capturing a Marketplace Authorization with a Foreign Retailer
- Multiple Partial Captures
  - Required Fields for Processing Multiple Partial Captures
  - REST Example: Processing Multiple Partial Captures
- Refunds
  - Required Fields for Processing a Refund
  - REST Interactive Example: Processing a Refund
  - REST Example: Processing a Refund
- Credits
  - Required Fields for Processing a Credit
  - REST Interactive Example: Processing a Credit
  - REST Example: Processing a Credit
- Voids for a Capture or Credit
  - Required Fields for Voiding a Capture or Credit
  - REST Example: Voiding a Capture or Credit

Debit and Prepaid Card Processing
- Processing Debit and Prepaid Authorizations
  - Required Fields for Processing Debit and Prepaid Authorizations
  - Optional Field for Processing Debit and Prepaid Authorizations
  - REST Example: Processing Debit and Prepaid Authorizations

Mastercard Processing
- Mastercard Payment of Winnings Processing
  - Required Fields for Processing a Mastercard Payment of Winnings
  - Optional Fields for Processing a Mastercard Payment of Winnings
  - REST Example: Processing a Mastercard Payment of Winnings

Payer Authentication Processing
- Providing Payer Authentication Information for Authorization
- Discover/Diners ProtectBuy
  - Required Fields for Processing an Authorization Using Discover ProtectBuy Authentication
  - REST Example: Processing an Authorization Using Discover ProtectBuy Authentication
- Mastercard Identity Check
  - Required Fields for Processing an Authorization Using Mastercard Identity Check
  - REST Example: Processing an Authorization Using Mastercard Identity Check
- Visa Secure
  - Required Fields for Processing an Authorization Using Visa Secure
  - REST Example: Validating and Authorizing a Transaction

Relaxed Requirements for Address Data and Expiration Date in Payment Transactions
- Requirements
- Services
- Relaxed Fields

Processing Payments Using Credentials
- Customer-Initiated Transactions with Credentials on File
  - Storing Customer Credentials with a CIT and PAN
    - Required Fields for Storing Customer Credentials During a CIT
    - REST Example: Storing Customer Credentials During a CIT
  - Storing Customer Credentials with a CIT and TMS
    - Required Fields for Storing Customer Credentials with a CIT and TMS
    - REST Example: Storing Customer Credentials with a CIT and TMS
  - Retrieving Stored Customer Credentials During a CIT
    - Required Fields for Retrieving Customer Credentials During a Customer-Initiated Transaction
      - Card-Specific Required Field for Retrieving Customer Credentials During a CIT
    - REST Example: Retrieving Customer Credentials During a CIT
- Delayed Transaction
  - Merchant-Initiated Delayed Transaction with PAN
    - Required Fields for Processing a Merchant-Initiated Delayed Transaction
      - Card-Specific Required Field for Processing a Merchant-Initiated Transactions
    - REST Example: Processing a Merchant-Initiated Delayed Authorization Transaction
  - Merchant-Initiated Delayed Transaction with TMS
    - Required Fields for MIT Delayed Transaction with TMS
    - Example: MIT Delayed Transaction with TMS Instrument Identifier
    - Example: MIT Delayed Transaction with TMS Payment Instrument
    - Example: MIT Delayed Transaction with TMS Customer token
- Incremental Transaction
  - Merchant-Initiated Incremental Transaction with PAN
    - Required Fields for Processing Merchant-Initiated Incremental Transactions
      - Card-Specific Required Field for Processing a Merchant-Initiated Transactions
    - REST Example: Processing Merchant-Initiated Incremental Transactions
  - Merchant-Initiated Incremental Transaction with TMS
    - Required Fields for MIT Incremental Transaction with TMS
    - Example: MIT Incremental Transaction with a TMS Instrument Identifier
    - Example: MIT Incremental Transaction with a TMS Payment Instrument
    - Example: MIT Incremental Transaction with a TMS Customer token
- No-Show Transactions
  - Merchant-Initiated No-Show Transactions with PAN
    - Required Fields for Processing Merchant-Initiated No-Show Charges
      - Card-Specific Required Field for Processing a Merchant-Initiated Transactions
    - Optional Field for Processing Merchant-Initiated No-Show Charges
    - REST Example: Processing Merchant-Initiated No-Show Transactions
  - Merchant-Initiated No-Show Transaction with TMS
    - Required Fields for MIT No-Show Transaction with TMS
    - Example: MIT No-Show Transaction with a TMS Instrument Identifier
    - Example: MIT No-Show Transaction with a TMS Payment Instrument
    - Example: MIT No-Show Transaction with a TMS Customer
- Reauthorization Transaction
  - Merchant-Initiated Reauthorization Transactions with PAN
    - Required Fields for Processing Merchant-Initiated Reauthorized Transactions
      - Card-Specific Required Field for Processing a Merchant-Initiated Transactions
    - REST Example: Processing a Merchant-Initiated Reauthorized Transaction
  - Merchant-Initiated Reauthorization Transactions with TMS
    - Required Fields for MIT Reauthorization Transaction with TMS
    - Example: MIT Reauthorization Transaction with a TMS Instrument Identifier
    - Example: MIT Reauthorization Transaction with a TMS Payment Instrument
    - Example: MIT Reauthorization Transaction with a TMS Customer
- Resubmission Transaction
  - Merchant-Initiated Resubmission Transaction with PAN
    - Required Fields for Processing a Merchant-Initiated Resubmitted Transaction
      - Card-Specific Required Field for Processing a Merchant-Initiated Transactions
    - REST Example: Processing a Merchant-Initiated Resubmitted Transaction
  - Merchant-Initiated Resubmission Transaction with TMS
    - Required Fields for MIT Resubmission Transaction with TMS
    - Example: MIT Resubmission Transaction with a TMS Instrument Identifier
    - Example: MIT Resubmission Transaction with a TMS Payment Instrument
    - Example: MIT Reauthorization Transaction with a TMS Customer
- Recurring Payments
  - Customer-Initiated Recurring Payment with PAN
    - Required Fields for Authorizing a Customer-Initiated Recurring Payment with PAN
    - REST Example: Authorizing a Customer-Initiated Recurring Payment with a PAN
  - Customer-Initiated Recurring Payment with TMS
    - Required Fields for Authorizing a Customer-Initiated Recurring Payment with TMS
    - REST Example: Authorizing a Customer-Initiated Recurring Payment with TMS
  - Customer-Initiated Recurring Payment with Enrollable Network Tokens
    - Required Fields for Authorizing a Customer-Initiated Recurring Payments with Enrollable Network Tokens
    - REST Example: Authorizing a Customer-Initiated Recurring Payment with Enrollable Network Tokens
  - Merchant-Initiated Recurring Payments with PAN
    - Required Fields for Authorizing a Merchant-Initiated Recurring Payment
      - Card-Specific Required Fields for Authorizing Subsequent Recurring Payments
    - REST Example: Authorizing a Merchant-Initiated Recurring Payment
  - Merchant-Initiated Recurring Payments with TMS
    - Required Fields for Authorizing a Merchant-Initiated Recurring Payments with TMS
    - REST Example: Authorizing a Merchant-Initiated Recurring Payment with a TMS Instrument Identifier
    - REST Example: Authorizing a Merchant-Initiated Recurring Payment with TMS Payment Instrument
    - REST Example: Authorizing a Merchant-Initiated Recurring Payment with a TMS Customer Token
- Mastercard Standing Order Payments
  - Mastercard Initial CIT Standing Order Payment
    - Required Fields for Authorizing Initial CIT Standing Order Payments
    - REST Example: Authorizing Initial CIT Standing Order Payments
  - Mastercard Initial CIT Standing Order Payment with TMS
    - Required Fields for Authorizing Initial CIT Standing Order Payments with TMS
    - REST Example: Authorizing Initial CIT Standing Order Payments with TMS
- Mastercard Subscription Payments
  - Mastercard CIT Initial Subscription Payment
    - Required Fields for Authorizing CIT Initial Subscription Payments
    - REST Example: Authorizing Initial CIT Subscription Payments
  - Mastercard CIT Initial Subscription Payment with TMS
    - Required Fields for Authorizing CIT Initial Subscription Payments with TMS
    - REST Example: Authorizing Initial CIT Subscription Payments with TMS
- Unscheduled COF Payments
  - Customer-Initiated Unscheduled COF Payment with PAN
    - Required Fields for a Customer-Initiated Unscheduled COF Payment with PAN
    - REST Example: Customer-Initiated Unscheduled COF Payment with PAN
  - Customer-Initiated Unscheduled COF Payments with TMS
    - Required Fields for CIT Unscheduled COF Payments with TMS
    - REST Example: Initial CIT Unscheduled COF Payment in TMS
  - Customer-Initiated Unscheduled COF Payment with Enrollable Network Tokens
    - Required Fields for CIT Unscheduled COF Payment with Enrollable Network Tokens
    - REST API Example: CIT Unscheduled COF Payment with Enrollable Network Tokens
  - Merchant-Initiated Unscheduled COF Payments with PAN
    - Required Fields for Authorizing Subsequent MIT Unscheduled COF Payments
      - Card-Specific Required Field for Processing a Merchant-Initiated Transactions
    - REST Example: Authorizing Subsequent MIT Unscheduled COF Payments
  - Merchant-Initiated Unscheduled COF Payments with TMS
    - Required Fields for MIT Unscheduled COF Payments with TMS
    - Example: MIT Unscheduled COF Payment with TMS Instrument Identifier
    - Example: MIT Unscheduled COF Payment with TMS Payment Instrument
    - Example: MIT Unscheduled COF Payment with TMS Customer

Token Management Service Processing
- Authorizing a Payment with a Customer Token
  - Required Fields for Authorizing a Payment with a Customer Token
  - REST Example: Authorizing a Payment with a Customer Token
  - REST Example: Authorizing a Payment Using a Customer Token Linked to a Network Token
- Authorizing a Payment with a Non-Default Shipping Address
  - Required Fields for Authorizing a Payment with a Non-Default Shipping Address
  - REST Example: Authorizing a Payment with a Non-Default Shipping Address
- Authorizing a Payment with a Non-Default Payment Instrument
  - Required Fields for Authorizing a Payment with a Non-Default Payment Instrument
  - Optional Fields for Authorizing a Payment with a Non-Default Payment Instrument
  - REST Example: Authorizing a Payment with a Non-Default Payment Instrument
- Authorizing a Payment with a Payment Instrument
  - Required Fields for Authorizing a Payment with a Payment Instrument
  - Optional Fields for Authorizing a Payment with a Payment Instrument
  - REST Example: Authorizing a Payment with a Payment Instrument
- Authorize a Payment with an Instrument Identifier
  - Required Fields for Authorizing a Payment with an Instrument Identifier
  - REST Example: Authorizing a Payment with an Instrument Identifier
  - REST Example: Authorizing a Payment with an Instrument Identifier While Creating TMS Tokens
- Authorize a Payment While Ignoring Network Token
  - Required Fields for Authorizing a Payment While Ignoring Network Token
  - REST Example: Authorizing a Payment While Ignoring Network Token
- Authorizing a Payment with a Legacy Token
  - Required Fields for Authorizing a Payment with a Legacy Token
  - REST Example: Authorizing a Payment with a Legacy Token
- Making a Credit with a Customer Token
  - Required Fields for Making a Credit with a Customer Token
  - REST Example: Making a Credit with a Customer Token
- Making a Credit with a Non-Default Payment Instrument
  - Required Fields for Making a Credit with a Non-Default Payment Instrument
  - Optional Fields for Making a Credit with a Non-Default Payment Instrument
  - REST Example: Making a Credit with a Non-Default Payment Instrument
- Making a Credit with a Payment Instrument
  - Required Fields for Making a Credit with a Payment Instrument
  - REST Example: Making a Credit with a Payment Instrument
- Making a Credit with an Instrument Identifier
  - Required Fields for Making a Credit with an Instrument Identifier
  - REST Example: Making a Credit with an Instrument Identifier
- Making a Credit with a Legacy Token
  - Required Fields for Making a Credit with a Legacy Token
  - REST Example: Making a Credit with a Legacy Token

On This Page

REST Example: Processing an Authorization Using Discover ProtectBuy Authentication

Request

{
"clientReferenceInformation": {
  "code": "TC50171_3"
},
"processingInformation": {
  "commerceIndicator": "dipb"
},
"paymentInformation": {
  "card": {
    "number": "60110000XXXXXXX2",
    "expirationMonth": "01",
    "expirationYear": "2026"
  }
},
"orderInformation": {
  "amountDetails": {
    "totalAmount": "100",
    "currency": "USD"
},
"billTo": {
  "firstName": "John",
  "lastName": "Smith",
  "address1": "201 S. Division St._1",
  "address2": "",
  "locality": "Foster City",
  "administrativeArea": "CA",
  "postalCode": "94404",
  "country": "US",
  "email": "[email protected]",
  "phoneNumber": "6504327113"
  }
},
  "consumerAuthenticationInformation": {
  "cavv": "1234567890987654321ABCDEFabcdefABCDEF123",
    "xid": "1234567890987654321ABCDEFabcdefABCDEF123"
  }
}

Response to a Successful Request

{
  "_links": {
    "authReversal": {
      "method": "POST",
      "href": "/pts/v2/payments/6764027854656733303954/reversals"
    },
    "self": {
      "method": "GET",
      "href": "/pts/v2/payments/6764027854656733303954"
    },
    "capture": {
      "method": "POST",
      "href": "/pts/v2/payments/6764027854656733303954/captures"
    }
  },
  "clientReferenceInformation": {
    "code": "TC50171_3"
  },
  "id": "6764027854656733303954",
  "orderInformation": {
    "amountDetails": {
      "authorizedAmount": "100.00",
      "currency": "USD"
    }
  },
  "paymentAccountInformation": {
    "card": {
      "type": "004"
    }
  },
  "paymentInformation": {
    "tokenizedCard": {
      "type": "004"
    },
    "card": {
      "type": "004"
    }
  },
  "pointOfSaleInformation": {
    "terminalId": "111111"
  },
  "processorInformation": {
    "approvalCode": "888888",
    "networkTransactionId": "123456789619999",
    "transactionId": "123456789619999",
    "responseCode": "100",
    "avs": {
      "code": "X",
      "codeRaw": "I1"
    }
  },
  "reconciliationId": "60125005GE39VNT8",
  "status": "AUTHORIZED",
  "submitTimeUtc": "2023-02-14T19:26:25Z"
}

Back to top