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
  - Japanese Payment Options
  - Payer Authentication
  - 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
- 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
- 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

Japanese Payment Options Processing
- Authorize a Single Payment with Japanese Payment Options
  - Required Fields for Authorizing a Single Payment Using the JPO Method
  - REST Example: Authorizing a JPO Single Payment
- Authorize a Bonus Payment with Japanese Payment Options
  - Required Fields for Authorizing a JPO Bonus Payment
  - REST Example: Authorizing a JPO Bonus Payment
- Authorize an Installment Payment with Japanese Payment Options
  - Required Fields for Authorizing a JPO Installment Payment
  - REST Example: Authorizing a JPO Installment Payment
- Authorize a Revolving Payment with Japanese Payment Options
  - Required Fields for Authorizing a Revolving Payment Using the JPO Method
  - REST Example: Authorizing a JPO Revolving Payment
- Authorize a Combination Payment with Japanese Payment Options
  - Required Fields for Authorizing a Combination Payment Using the JPO Method
  - REST Example: Authorizing a JPO Combination Payment

Payer Authentication Processing
- Additional Resources for Payer Authentication
- Providing Payer Authentication Information for Authorization
- American Express SafeKey
  - Required Fields for Processing an Authorization Using American Express SafeKey
  - Optional Field for Processing an Authorization Using American Express SafeKey
  - REST Example: Processing an Authorization Using American Express SafeKey
- JCB J/Secure
  - Required Fields for Processing an Authorization Using JCB J/Secure Authentication
  - REST Example: Processing an Authorization Using JCB J/Secure 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

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

Pre-Authorizations

This section provides the information you need in order to process a pre-authorization.

A pre-authorization enables you to authorize a payment when the final amount is unknown. It is typically used for lodging, auto rental, e-commerce, and restaurant transactions.

For a pre-authorization:

The authorization amount must be greater than zero.

The authorization must be submitted for capture within 30 calendar days of its request.

When you do not capture the authorization, you must reverse it.

In the U.S., Canada, Latin America, and Asia Pacific, Mastercard charges an additional fee for a pre-authorization that is not captured and not reversed.

In Europe, Russia, Middle East, and Africa, Mastercard charges fees for all pre-authorizations.

Chargeback protection is in effect for 30 days after the authorization.

Limitations for JCN Gateway:

The maximum amount that can be processed in an authorization is limited to 8 digits: 99,999,999.

The maximum amount that can be processed in a capture or credit is limited to 7 digits: 9,999,999.

The maximum amount that can be processed in a sale is limited to 7 digits: 9,999,999 (due to the capture limitation)

IMPORTANT

It is possible to authorize a transaction amount that is larger than the maximum supported capture amount. Multiple partial capture transactions can be combined to match the total authorization amount. This is then converted to a billable transaction record in the batch file that is sent to the processor for settlement.

Endpoint

Production:

POST https://api.cybersource.com/pts/v2/payments

Test:

POST https://apitest.cybersource.com/pts/v2/payments

Back to top