Developer Guide Menu

Service Fees for Credit Card Transactions

Service fees are supported for FDC Nashville Global for the following card types:
  • Visa
  • Mastercard
  • American Express
  • Discover

Requirements

As part of the checkout process on your web site, you must display a terms and conditions statement for the service fee. A customer must accept the terms and conditions before submitting an order.
To enable the service fee feature, contact CyberSource Customer Support to have your CyberSource account configured for it.

Limitations

Service fees have the following limitations:
  • Airline data is supported only for the principal amount, not for the service fee.
  • Level II and Level III data are supported only for the principal amount, not for the service fee.
  • The following features are not supported for transactions that include service fees:
    • AVS
    • CVN
    • Partial authorizations
    • Verbal authorizations

Merchant Reference Numbers

CyberSource provides a service that prevents duplicate merchant reference numbers for transactions. When this service is turned on for service fee transactions, it allows duplicate merchant reference numbers only for service fee transactions.
For more information about this service, or to turn the service on or off, contact CyberSource Customer Support.

Relaxed Requirements for Address Data and Expiration Date

To enable relaxed requirements for address data and expiration date, contact CyberSource Customer Support to have your account configured for this feature. For details about relaxed requirements, see the Relaxed Requirements for Address Data and ExpirationDate page.

Processing a Service Fee

Service fees in credit card transactions are processed in the following services:
  • Authorization
  • Full authorization reversal
  • Capture
  • Credit
  • Void
  • Authorization reversal after void

Calculating the Service Fee

  1. You include the following required fields in your request for the service fee calculate service:
    • orderInformation.amountDetails.currency
    • paymentInformation.card.number

      NOTE

      For a tokenized payment card, use 
      paymentInformation.tokenizedCard.number
      .
    • orderInformation.amountDetails.totalAmount or at least one offer-level amount field.
    • clientReferenceInformation.code
  2. One of the fields that CyberSource includes in the reply message is 
    service_fee_calculate_amount
    .

Authorizing the Principal Amount and Service Fee

  1. You include the following fields in your authorization request:
    • processingInformation.authorizationOptions.ignoreAvsResult: Set this field to 
      yes
      .
    • processingInformation.authorizationOptions.ignoreCvResult: Set this field to 
      yes
      .
    • orderInformation.amountDetails.serviceFeeAmount: Set this field to the value of the 
      service_fee_calculate_amount
       field that you received in the service fee calculate reply message.

    NOTE

    The final authorization indicator is supported on FDC Nashville Global. For more information about the final authorization indicator, see .
    For information about creating an authorization request, see "Authorizations."

    NOTE

    CyberSource always provides values for the following service fee merchant descriptor fields to FDC Nashville Global for all service fee authorization transactions:
    • merchantInformation.serviceFeeDescriptor.name
    • merchantInformation.serviceFeeDescriptor.contact
    • merchantInformation.serviceFeeDescriptor.state
    POST https://<url_prefix>/pts/v2/payments/
    Request payload
    { "clientReferenceInformation" : { "code" : "TC50171_3" }, "processingInformation" : { "commerceIndicator" : "internet" }, "orderInformation" : { "billTo": { "firstName": "John", "lastName": "Doe", "address1": "1 Market St", "postalCode": "94105", "locality": "san francisco", "administrativeArea": "CA", "country": "US", "email": "test@cybs.com" }, "amountDetails" : { "totalAmount" : "2325.00", "currency" : "USD", "serviceFeeAmount":"30.0" } }, "paymentInformation" : { "card" : { "number" : "4111111111111111", "expirationMonth" : "12", "expirationYear" : "2031" } }, "merchantInformation" : { "serviceFeeDescriptor" : { "name" : "CyberSource Service Fee", "contact" : "800-999-9999", "state" : "CA" } } }
    For each service fee merchant descriptor, when you do not include the merchant descriptor value in your request, CyberSource uses the value that is in your CyberSource account. When the value is not included in your request or in your CyberSource account, FDC Nashville Global uses the value that is in your First Data merchant master file.
    To add a merchant descriptor value to your CyberSource account, contact CyberSource Customer Support.
  2. CyberSource sends an authorization request for the principal amount to the processor. The principal amount is either the value of the 
    orderInformation.amountDetails.totalAmount
     field or the sum of the amounts for all of the offers in the transaction.
  3. If the authorization for the principal amount fails, CyberSource returns the pertinent error information to you in the reply message, and none of the remaining events in this description occur.
  4. If the authorization for the principal amount succeeds, CyberSource sends an authorization request for the service fee to the processor. CyberSource sends the same authorization indicator value that was sent in the authorization request for the principal amount.
  5. If the authorization for the service fee fails, CyberSource reverses the authorization for the principal amount and returns the pertinent error information to you in the reply message, and none of the remaining events in this description occur.

Reversing an Authorization

If you decide to reverse the authorizations instead of capturing them, you must include values for the following fields in your request for a full authorization reversal:
  • Principal amount, which is either the value of the 
    orderInformation.amountDetails.totalAmount
     field or the sum of the values for all offers in the transaction.
  • orderInformation.amountDetails.serviceFeeAmount
For information about creating a request to reverse an authorization, see the CyberSource REST API Reference.
POST https://<url_prefix>/pts/v2/payments/{id}/reversals
Request payload
{ "clientReferenceInformation": { "code": "TC50171_3" }, "reversalInformation": { "reason": "34", "amountDetails": { "totalAmount": "2325.00", "serviceFeeAmount": "30.0" } } }

Capturing the Principal Amount and Service Fee

  1. If the authorization for the service fee succeeds, include the following values in your capture request:
    • Principal amount, which is either the value of the 
      orderInformation.amountDetails.totalAmount
       field or the sum of the values for all offers in the transaction.
    • orderInformation.amountDetails.serviceFeeAmount

    NOTE

    CyberSource always provides values for the following service fee merchant descriptor fields to FDC Nashville Global for all service fee authorization transactions:
    • merchantInformation.serviceFeeDescriptor.name
    • merchantInformation.serviceFeeDescriptor.contact
    • merchantInformation.serviceFeeDescriptor.state
    For each service fee merchant descriptor, when you do not include the merchant descriptor value in your request, CyberSource uses the value that is in your CyberSource account. When the value is not included in your request or in your CyberSource account, FDC Nashville Global uses the value that is in your First Data merchant master file.
    To add a merchant descriptor value to your CyberSource account, contact CyberSource Customer Support.
    Multiple captures are supported for the principal amount and service fee amount. In the first capture request, you must include the entire service fee amount that was authorized, or you can split the service fee amount between the first and subsequent capture requests. CyberSource recommends that you include the full service fee in the first capture request.
    Include the following special request fields in each capture request when you are requesting multiple partial captures:
    • processingInformation.captureOptions.captureSequenceNumber
    • processingInformation.captureOptions.totalCaptureCount
    For information about creating a capture request and multiple captures, see the CyberSourceREST API Reference.
  2. CyberSource examines the principal capture amount to determine whether it qualifies to be sent to the processor.
    The principal capture amount qualifies to be sent to the processor when any of the following statements are true:
    • It equals the authorized principal amount.
    • It is less than the authorized principal amount.
    • It exceeds the authorized principal amount, and your CyberSource account is configured to allow capture amounts to exceed authorized amounts.
    The principal capture amount does not qualify to be sent to the processor when any of the following statements are true:
    • It is not included in the request.
    • It is an invalid value.
    • It exceeds the authorized principal amount, and your CyberSource account is not configured to allow capture amounts to exceed authorized amounts.
  3. If the principal capture amount does not qualify to be sent to the processor, CyberSource returns the pertinent error information to you in the reply message. CyberSource does not submit the capture requests to the processor and does not reverse the authorized amounts, and none of the remaining events in this description occur.

    NOTE

    You can correct the principal capture amount and resend the capture request.
  4. If the principal capture amount qualifies to be sent to the processor, CyberSource examines the service fee capture amount to determine whether it qualifies to be sent to the processor.
    The service fee capture amount qualifies to be sent to the processor when any of the following statements are true:
    • It equals the authorized service fee amount.
    • It is less than the authorized service fee amount.
    • It exceeds the authorized service fee amount, and your CyberSource account is configured to allow capture amounts to exceed authorized amounts.
    The service fee capture amount does not qualify to be sent to the processor when any of the following statements are true:
    • It is not included in the request.
    • It is an invalid value.
    • It exceeds the authorized service fee amount, and your CyberSource account is not configured to allow capture amounts to exceed authorized amounts.
    • The authorization request did not include a service fee amount.
  5. If the service fee capture amount does not qualify to be sent to the processor, CyberSource returns the pertinent error information to you in the reply message. CyberSource does not submit the capture requests to the processor and does not reverse the authorized amounts, and none of the remaining events in this description occur.

    NOTE

    If the authorization and capture requests included a service fee amount, you can correct the service fee capture amount and resend the capture request.
    If the authorization request did not include a service fee amount, you can resend the capture request without the service fee amount.
  6. If the service fee capture amount qualifies to be sent to the processor, CyberSource sends the following requests to the processor:
    • Capture request for the principal amount.
    • Capture request for the service fee amount.
  7. If one or both captures fail, CyberSource returns the pertinent error information to you in the reply message, and none of the remaining events in this description occur. If one capture fails and the other capture succeeds, CyberSource does not void the successful capture.
  8. If both captures succeed, you have successfully authorized and captured the principal amount and the service fee.
POST https://<url_prefix>/pts/v2/payments/{id}/captures
Request payload
{ "clientReferenceInformation": { "code": "TC50171_3" }, "processingInformation" : { "commerceIndicator" : "internet" }, "orderInformation": { "amountDetails": { "totalAmount": "2325.00", "currency": "USD", "serviceFeeAmount": "30.0" } }, "merchantInformation" : { "serviceFeeDescriptor" : { "name" : "CyberSource Service Fee", "contact" : "800-999-9999", "state" : "CA" } } }

Crediting the Principal Amount and Service Fee

  1. You can credit the principal amount, the service fee amount, or both amounts (optional).
    • To credit only the principal amount, include values for one of the following in your credit request (
      /pts/v2/payments/{id}/refunds
       or 
      /pts/v2/captures/{id}/refunds
      ):
      • orderInformation.amountDetails.totalAmount
      • Sum of the amounts for all offers in the transaction
    • To credit only the service fee amount, include values for the following fields in your credit request (
      /pts/v2/payments/{id}/refunds
       or 
      /pts/v2/captures/{id}/refunds
      ):
      • orderInformation.amountDetails.serviceFeeAmount
      • orderInformation.amountDetails.totalAmount = 
        0
         (zero)
      • The request ID that was returned in the capture reply for the principal amount should be retrieved from the URL and mapped to
        /pts/v2/payments/{id}/refunds
         or 
        /pts/v2/captures/{id}/refunds
        .
    • To credit both amounts, include values for the following in your credit request (
      /pts/v2/payments/{id}/refunds
       or 
      /pts/v2/captures/{id}/refunds
      ):
      • Either the value of the 
        orderInformation.amountDetails.totalAmount
        field or the sum of the amounts for all the offers in the transaction
      • orderInformation.amountDetails.serviceFeeAmount

    NOTE

    CyberSource always provides values for the following service fee merchant descriptor fields to FDC Nashville Global for all service fee authorization transactions:
    • merchantInformation.serviceFeeDescriptor.name
    • merchantInformation.serviceFeeDescriptor.contact
    • merchantInformation.serviceFeeDescriptor.state
    When you do not include the merchant descriptor value in your request, CyberSource uses the value that is in your CyberSource account. When the value is not included in your request or in your CyberSource account, FDC Nashville Global uses the value that is in your First Data merchant master file.
    To add a merchant descriptor value to your CyberSource account, contact CyberSource Customer Support.
    For information about creating a credit request, see the CyberSource REST API Reference.
  2. If the service fee credit amount qualifies to be sent to the processor, CyberSource sends the following requests to the processor:
    • Credit request for the principal amount
    • Credit request for the service fee amount
  3. If one or both credits fail, CyberSource returns the pertinent error information to you in the reply message, and none of the remaining events in this description occur.
    If one credit fails and the other credit succeeds, CyberSource does not void the successful credit.
  4. If both credits succeed, you have successfully credited the principal amount and the service fee.

Voiding a Capture or Credit

You can void captures and credits. See "Voids."
For more information about voiding captures and credits, see the CyberSourceREST API Reference.

Reversing an Authorization after a Void

If you decide to reverse the authorizations after a void, you must include values for the following in your request for a full authorization reversal:
  • Principal amount, which is either the value of the 
    orderInformation.amountDetails.totalAmount
     field or the sum of the amounts for all the offers in the transaction
  • orderInformation.amountDetails.serviceFeeAmount
For information about authorization reversal after void (ARAV), see the CyberSourceREST API Reference.
POST https://<url_prefix>/pts/v2/payments/{id}/reversals
Request payload
{ "clientReferenceInformation": { "code": "TC50171_3" }, "reversalInformation": { "reason": "34", "amountDetails": { "totalAmount": "2325.00", "serviceFeeAmount": "30.0" } } }
Top