Processing a Service Fee

The fields mentioned in this section are described in "Request Fields," page 22. Additional fields for authorizations, authorization reversals, captures, credits, and voids are described in Credit Card Services Using the Simple Order API.

Service fees in credit card transactions are processed in the following services:

■	Service fee calculation

■	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:

■	card_accountNumber

■	merchantID

■	merchantReferenceCode

■	purchaseTotals_currency

■	purchaseTotals_grandTotalAmount or at least one item_#_unitPrice field.

■	serviceFeeCalculateService_run: Set this field to true.

2	One of the fields that CyberSource includes in the reply message is serviceFeeCalculateReply_amount.

Authorizing the Principal Amount and Service Fee

1	You include the following fields in your authorization request:

■	businessRules_ignoreAVSResult: Set this field to true.

■	businessRules_ignoreCVResult: Set this field to true.

■	purchaseTotals_serviceFeeAmount: Set this field to the value of the serviceFeeCalculateReply_amount field that you received in the service fee calculate reply message.

 

The final authorization indicator is supported on FDC Nashville Global. For more information about the final authorization indicator, see Credit Card Services Using the Simple Order API.

For information about creating an authorization request, see Credit Card Services Using the Simple Order API.

 

CyberSource always provides the following service fee merchant descriptor values to FDC Nashville Global for all service fee authorization transactions: ■ serviceFee_merchantDescriptor ■ serviceFee_merchantDescriptorContact ■ serviceFee_merchantDescriptorState 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 purchaseTotals_grandTotalAmount or the sum of the amounts for all of the items 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 the following values in your request for a full authorization reversal:

■	Principal amount, which is either the value of purchaseTotals_grandTotalAmount or the sum of the amounts for all the items in the transaction

■	purchaseTotals_serviceFeeAmount

For information about creating a request to reverse an authorization, see Credit Card Services Using the Simple Order API.

Capturing the Principal Amount and Service Fee

1	If the authorization for the service fee succeeds, you include the following values in your capture request:

■	Principal amount, which is either the value of purchaseTotals_grandTotalAmount or the sum of the amounts for all the items in the transaction

■	purchaseTotals_serviceFeeAmount

 

CyberSource always provides the following service fee merchant descriptor values to FDC Nashville Global for all service fee capture transactions: ■ serviceFee_merchantDescriptor ■ serviceFee_merchantDescriptorContact ■ serviceFee_merchantDescriptorState 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:

■	ccCaptureService_sequence

■	ccCaptureService_totalCount

For information about creating a capture request and multiple captures, see Credit Card Services Using the Simple Order API.

 

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.

 

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.

 

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.

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 one of the following values in your credit request:

●	purchaseTotals_grandTotalAmount

●	Sum of the amounts for all items in the transaction

■	To credit only the service fee amount, include the following fields and values in your credit request:

●	purchaseTotals_serviceFeeAmount

●	purchaseTotals_grandTotalAmount = 0 (zero)

●	ccCreditService_captureRequestID = request ID that was returned in the capture reply for the principal amount

■	To credit both amounts, include the following values in your credit request:

●	Either the value of purchaseTotals_grandTotalAmount or the sum of the amounts for all the items in the transaction

●	purchaseTotals_serviceFeeAmount

 

CyberSource always provides the following service fee merchant descriptor values to FDC Nashville Global for all service fee capture transactions: ■ serviceFee_merchantDescriptor ■ serviceFee_merchantDescriptorContact ■ serviceFee_merchantDescriptorState 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.

For information about creating a credit request, see Credit Card Services Using the Simple Order API.

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.

For information about voiding captures and credits, see Credit Card Services Using the Simple Order API.

Reversing an Authorization after a Void

If you decide to reverse the authorizations after a void, you must include the following values in your request for a full authorization reversal:

■	Principal amount, which is either the value of purchaseTotals_grandTotalAmount or the sum of the amounts for all the items in the transaction

■	purchaseTotals_serviceFeeAmount

 

For information about authorization reversal after void (ARAV), see Credit Card Services Using the Simple Order API.