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
  - International Transactions
    - Compliance
    - Merchant Remittance Funding
  - 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
  - Payer Authentication
  - Introduction to Credentialed Transactions
  - Token Management Service
  - Visa Bill Payments
- 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
- 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
- Multiple Partial Captures
  - Required Fields for Processing Multiple Partial Captures
  - REST Example: Processing Multiple Partial Captures
- Forced Captures
  - Required Fields for Forced Captures
  - REST Example: Forced 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
- Additional Resources for Debit and Prepaid Payments
- 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
- Enabling Debit and Prepaid Partial Authorizations
  - Required Fields for Enabling Debit and Prepaid Partial Authorizations
  - Optional Field for Enabling Debit and Prepaid Partial Authorizations
  - REST Example: Enabling Debit and Prepaid Partial Authorizations
- Disabling Debit and Prepaid Partial Authorizations
  - Required Field for Disabling Debit and Prepaid Partial Authorizations
  - Optional Field for Disabling Debit and Prepaid Partial Authorizations
  - REST Example: Disabling Debit and Prepaid Partial Authorizations

Payer Authentication Processing
- Additional Resources for Payer Authentication
- Providing Payer Authentication Information for Authorization
- 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

Processing Payments Using Credentials
- Additional Resources for Credentialed Transactions
- 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

Token Management Service Processing
- Additional Resources for TMS
- 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

Visa Bill Payments Processing
- Visa Bill Payments Authorizations
  - Required Fields for Processing a Visa Bill Payment Authorization
  - REST Example: Processing a Visa Bill Payment Authorization
- Visa Bill Payments Captures
  - Required Fields for Capturing a Visa Bill Payment
  - REST Example: Capturing a Visa Bill Payment

On This Page

Declined Authorizations

If an authorization is declined, you can use response categories to help you decide whether to retry or block a declined transaction. These response fields provide additional information:

paymentInsightsInformation.responseInsights.category

paymentInsightsInformation.responseInsights.categoryCode

Category codes have possible values (such as

01

) each of which corresponds to a category that contains a description.

You cannot retry this category code and category:

01 ISSUER_WILL_NEVER_APPROVE

For these values, you can retry the transaction a maximum of 15 times over a period of 30 days:

02 ISSUER_CANNOT_APPROVE_AT_THIS_TIME

03 ISSUER_CANNOT_APPROVE_WITH_THESE_DETAILS

: Data quality issue. Revalidate data prior to retrying the transaction.

04 GENERIC_ERROR

97 PAYMENT_INSIGHTS_INTERNAL_ERROR

98 OTHERS

99 PAYMENT_INSIGHTS_RESPONSE_CATEGORY_MATCH_NOT_FOUND

Back to top