CyberSource reversal API
An authorization reversal releases the hold that the payment placed on the customer's funds.
OpenAPI Specification
swagger: '2.0'
info:
description: All CyberSource API specs merged together. These are available at https://developer.cybersource.com/api/reference/api-reference.html
version: 0.0.1
title: CyberSource Merged Spec bankAccountValidation reversal API
host: apitest.cybersource.com
basePath: /
schemes:
- https
consumes:
- application/json;charset=utf-8
produces:
- application/hal+json;charset=utf-8
tags:
- name: reversal
description: An authorization reversal releases the hold that the payment placed on the customer's funds.
paths:
/pts/v2/payments/{id}/reversals:
post:
summary: Process an Authorization Reversal
description: Include the payment ID in the POST request to reverse the payment amount.
tags:
- reversal
operationId: authReversal
x-devcenter-metaData:
categoryTag: Payments
developerGuides: https://developer.cybersource.com/docs/cybs/en-us/payments/developer/ctv/rest/payments/payments-intro.html
isMLEsupported: true
mleForRequest: optional
parameters:
- name: id
in: path
description: The payment ID returned from a previous payment request.
required: true
type: string
- name: authReversalRequest
in: body
required: true
schema:
type: object
properties:
clientReferenceInformation:
type: object
properties:
code:
type: string
maxLength: 59
description: 'Merchant-generated order reference or tracking number. It is recommended that you send a unique value for each
transaction so that you can perform meaningful searches for the transaction.
#### Used by
**Authorization**
Required field.
#### PIN Debit
Requests for PIN debit reversals need to use the same merchant reference number that was used in the transaction that is being
reversed.
Required field for all PIN Debit requests (purchase, credit, and reversal).
#### FDC Nashville Global
Certain circumstances can cause the processor to truncate this value to 15 or 17 characters for Level II and Level III processing, which can cause a discrepancy between the value you submit and the value included in some processor reports.
'
pausedRequestId:
type: string
maxLength: 26
description: 'Used to resume a transaction that was paused for an order modification rule to allow for payer authentication to complete. To resume and continue with the authorization/decision service flow, call the services and include the request id from the prior decision call.
'
comments:
type: string
description: Brief description of the order or any comment you wish to add to the order.
partner:
type: object
properties:
developerId:
type: string
maxLength: 8
description: 'Identifier for the developer that helped integrate a partner solution to CyberSource.
Send this value in all requests that are sent through the partner solutions built by that developer.
CyberSource assigns the ID to the developer.
**Note** When you see a developer ID of 999 in reports, the developer ID that was submitted is incorrect.
'
solutionId:
type: string
maxLength: 8
description: 'Identifier for the partner that is integrated to CyberSource.
Send this value in all requests that are sent through the partner solution. CyberSource assigns the ID to the partner.
**Note** When you see a solutionId of 999 in reports, the solutionId that was submitted is incorrect.
'
thirdPartyCertificationNumber:
type: string
maxLength: 12
description: 'Value that identifies the application vendor and application version for a third party gateway.
CyberSource provides you with this value during testing and validation.
This field is supported only on CyberSource through VisaNet.
#### Used by
**Authorization, Authorization Reversal, Capture, Credit, Incremental Authorization, and Void**
Optional field.
#### PIN debit
Required field for PIN debit credit, PIN debit purchase, or PIN debit reversal request.
'
applicationName:
type: string
description: 'The name of the Connection Method client (such as Virtual Terminal or SOAP Toolkit API) that the merchant uses to send a transaction request to CyberSource.
'
applicationVersion:
type: string
description: 'Version of the CyberSource application or integration used for a transaction.
'
applicationUser:
type: string
description: 'The entity that is responsible for running the transaction and submitting the processing request to CyberSource. This could be a person, a system, or a connection method.
'
reconciliationId:
type: string
maxLength: 60
description: 'Reference number for the transaction.
Depending on how your Cybersource account is configured, this value could either be provided in the API request or generated by CyberSource.
The actual value used in the request to the processor is provided back to you by Cybersource in the response.
'
transactionId:
type: string
maxLength: 30
description: 'Identifier that you assign to the transaction. Normally generated by a client server to identify a unique API request.
**Note** Use this field only if you want to support merchant-initiated reversal and void operations.
#### Used by
**Authorization, Authorization Reversal, Capture, Credit, and Void**
Optional field.
#### PIN Debit
For a PIN debit reversal, your request must include a request ID or a merchant transaction identifier.
Optional field for PIN debit purchase or credit requests.
'
reversalInformation:
type: object
properties:
amountDetails:
type: object
properties:
totalAmount:
type: string
maxLength: 19
description: "Grand total for the order. This value cannot be negative. You can include a decimal point (.), but no other special characters.\nCyberSource truncates the amount to the correct number of decimal places.\n\n**Note** For CTV, FDCCompass, Paymentech processors, the maximum length for this field is 12.\n\n**Important** Some processors have specific requirements and limitations, such as maximum amounts and maximum field lengths.\n\nIf your processor supports zero amount authorizations, you can set this field to 0 for the authorization to check if the card is lost or stolen. \n\n#### Card Present\nRequired to include either this field or `orderInformation.lineItems[].unitPrice` for the order.\n\n#### Invoicing / Pay By Link\nRequired for creating a new invoice or payment link.\n\n#### PIN Debit\nAmount you requested for the PIN debit purchase. This value is returned for partial authorizations. The issuing bank can approve a partial amount if the balance on the debit card is less than the requested transaction amount.\n\nRequired field for PIN Debit purchase and PIN Debit credit requests.\nOptional field for PIN Debit reversal requests.\n\n#### GPX\nThis field is optional for reversing an authorization or credit; however, for all other processors, these fields are required.\n\n#### DCC with a Third-Party Provider\nSet this field to the converted amount that was returned by the DCC provider. You must include either this field or the 1st line item in the order and the specific line-order amount in your request. \n\n#### DCC for First Data\nNot used.\n"
currency:
type: string
maxLength: 3
description: 'Currency used for the order. Use the three-character [ISO Standard Currency Codes.](http://apps.cybersource.com/library/documentation/sbc/quickref/currencies.pdf)
#### Used by
**Authorization**
Required field.
**Authorization Reversal**
For an authorization reversal (`reversalInformation`) or a capture (`processingOptions.capture` is set to `true`), you must use the same currency that you used in your payment authorization request.
#### PIN Debit
Currency for the amount you requested for the PIN debit purchase. This value is returned for partial authorizations. The issuing bank can approve a partial amount if the balance on the debit card is less than the requested transaction amount. For the possible values, see the [ISO Standard Currency Codes](https://developer.cybersource.com/library/documentation/sbc/quickref/currencies.pdf).
Returned by PIN debit purchase.
For PIN debit reversal requests, you must use the same currency that was used for the PIN debit purchase or PIN debit credit that you are reversing.
For the possible values, see the [ISO Standard Currency Codes](https://developer.cybersource.com/library/documentation/sbc/quickref/currencies.pdf).
Required field for PIN Debit purchase and PIN Debit credit requests.
Optional field for PIN Debit reversal requests.
#### GPX
This field is optional for reversing an authorization or credit.
#### DCC for First Data
Your local currency.
#### Tax Calculation
Required for international tax and value added tax only.
Optional for U.S. and Canadian taxes.
Your local currency.
'
reason:
type: string
description: "Reason for the authorization reversal. Possible value:\n\n - `34`: Suspected fraud\n\nThis field is ignored for processors that do not support this value.\n\nReturned by authorization reversal.\n"
processingInformation:
type: object
properties:
paymentSolution:
type: string
maxLength: 12
description: "Type of digital payment solution for the transaction. Possible Values:\n\n - `visacheckout`: Visa Checkout. This value is required for Visa Checkout transactions. For details, see `payment_solution` field description in [Visa Checkout Using the REST API.](https://developer.cybersource.com/content/dam/docs/cybs/en-us/apifields/reference/all/rest/api-fields.pdf)\n - `001`: Apple Pay.\n - `004`: Cybersource In-App Solution.\n - `005`: Masterpass. This value is required for Masterpass transactions on OmniPay Direct. \n - `006`: Android Pay.\n - `007`: Chase Pay.\n - `008`: Samsung Pay.\n - `012`: Google Pay.\n - `013`: Cybersource P2PE Decryption\n - `014`: Mastercard credential on file (COF) payment network token. Returned in authorizations that use a payment network token associated with a TMS token.\n - `015`: Visa credential on file (COF) payment network token. Returned in authorizations that use a payment network token associated with a TMS token.\n - `027`: Click to Pay.\n"
reconciliationId:
type: string
maxLength: 60
description: 'Please check with Cybersource customer support to see if your merchant account is configured correctly so you
can include this field in your request.
* For Payouts: max length for FDCCompass is String (22).
'
linkId:
type: string
maxLength: 26
description: 'Value that links the current authorization request to the original authorization request. Set this value
to the ID that was returned in the reply message from the original authorization request.
This value is used for:
- Partial authorizations
- Split shipments
'
reportGroup:
type: string
maxLength: 25
description: 'Attribute that lets you define custom grouping for your processor reports. This field is supported only for **Worldpay VAP**.
'
visaCheckoutId:
type: string
maxLength: 48
description: 'Identifier for the **Visa Checkout** order. Visa Checkout provides a unique order ID for every transaction in
the Visa Checkout **callID** field.
'
issuer:
type: object
properties:
discretionaryData:
type: string
maxLength: 255
description: 'Data defined by the issuer.
The value for this reply field will probably be the same as the value that you submitted in the authorization request, but it is possible for the processor, issuer, or acquirer to modify the value.
This field is supported only for Visa transactions on **CyberSource through VisaNet**.
'
actionList:
type: array
description: 'Array of actions (one or more) to be included in the reversal
Possible value:
- `AP_AUTH_REVERSAL`: Use this when you want to reverse an Alternative Payment Authorization.
'
items:
type: string
transactionTypeIndicator:
type: string
maxLength: 3
description: 'This field is used identify the type of payment transaction taking place. This field is applicable for MasterCard transactions only.
Possible values:
- 201- Mastercard Rebate
- 202- rePower Load Value
- 203- Gaming Re-pay
- 204- General Person-to-Person
- 205- General Transfer to Own Account
- 206- Agent Cash Out
- 207- Payment of Own Credit Card Bill
- 208- Business Disbursement
- 209- Government/Non-Profit Disbursement
- 210- Rapid Merchant Settlement
- 211- Cash in at ATM (Usage limited to specific countries)
- 212- Cash in at Point of Sale (Usage limited to specific countries)
- 213- General Business to Business Transfer
- 214- Mastercard Merchant Presented QR
- 215- Mastercard Merchant Presented QR Refund Payment
- 216- Utility Payments (for Brazil domestic use only)
- 217- Government Services (for Brazil domestic use only)
- 218- Mobile phone top-ups (for Brazil domestic use only)
- 219- Coupon booklet payments (for Brazil domestic use only)
- 220- General Person-to-Person Transfer
- 221- Person-to-Person Transfer to Card Account
- 222- General Transfer to Own Account
- 223- Agent Cash Out
- 224- Payment of Own Credit Card Bill
- 225- Business Disbursement
- 226- Transfer to Own Staged Digital Wallet Account
- 227- Transfer to Own Debit or Prepaid Account
- 228- General Business-to-Business Transfer
- 229- Installment-based repayment
- 230- Mastercard ATM Cash Pick-Up Transaction
- 231- Cryptocurrency
- 232- High-risk Securities
'
orderInformation:
type: object
properties:
amountDetails:
type: object
properties:
serviceFeeAmount:
type: string
maxLength: 15
description: 'Service fee. Required for service fee transactions.
'
lineItems:
type: array
items:
type: object
properties:
quantity:
type: integer
minimum: 1
maximum: 999999999
default: 1
description: 'Number of units for this order. Must be a non-negative integer.
The default is `1`. For an authorization or capture transaction (`processingOptions.capture` is set to `true` or `false`),
this field is required when `orderInformation.lineItems[].productCode` is not `default` or one of the other values
related to shipping and/or handling.
#### Tax Calculation
Optional field for U.S., Canadian, international tax, and value added taxes.
'
unitPrice:
type: string
maxLength: 15
description: 'Per-item price of the product. This value for this field cannot be negative.
You must include either this field or the request-level field `orderInformation.amountDetails.totalAmount` in your request.
You can include a decimal point (.), but you cannot include any other special characters.
The value is truncated to the correct number of decimal places.
#### DCC with a Third-Party Provider
Set this field to the converted amount that was returned by the DCC provider. You must include either
the 1st line item in the order and this field, or the request-level field `orderInformation.amountDetails.totalAmount` in your request.
#### Tax Calculation
Required field for U.S., Canadian, international and value added taxes.
#### Zero Amount Authorizations
If your processor supports zero amount authorizations, you can set this field to 0 for the
authorization to check if the card is lost or stolen.
#### Maximum Field Lengths
For GPN and JCN Gateway: Decimal (10)
All other processors: Decimal (15)
'
pointOfSaleInformation:
type: object
properties:
emv:
type: object
properties:
tags:
type: string
maxLength: 1998
description: "EMV data that is transmitted from the chip card to the issuer, and from the issuer to the chip card. The EMV\ndata is in the tag-length-value format and includes chip card tags, terminal tags, and transaction detail tags.\n\nFor information about the individual tags, see the \"Application Specification\" section in the EMV 4.3 Specifications: http://emvco.com\n\n**Note** Card present information about EMV applies only to credit card processing and PIN debit processing.\nAll other card present information applies only to credit card processing. PIN debit processing is available only\non FDC Nashville Global.\n\n**Important** The following tags contain sensitive information and **must not** be included in this field:\n\n - `56`: Track 1 equivalent data\n - `57`: Track 2 equivalent data\n - `5A`: Application PAN\n - `5F20`: Cardholder name\n - `5F24`: Application expiration date (This sensitivity has been relaxed for Credit Mutuel-CIC, American Express Direct, FDC Nashville Global, First Data Merchant Solutions, and SIX)\n - `99`: Transaction PIN\n - `9F0B`: Cardholder name (extended)\n - `9F1F`: Track 1 discretionary data\n - `9F20`: Track 2 discretionary data\n\nFor captures, this field is required for contact EMV transactions. Otherwise, it is optional.\n\nFor credits, this field is required for contact EMV stand-alone credits and contactless EMV stand-alone credits.\nOtherwise, it is optional.\n\n**Important** For contact EMV captures, contact EMV stand-alone credits, and contactless EMV stand-alone credits,\nyou must include the following tags in this field. For all other types of EMV transactions, the following tags\nare optional.\n\n - `95`: Terminal verification results\n - `9F10`: Issuer application data\n - `9F26`: Application cryptogram\n\n\n#### CyberSource through VisaNet\n- In Japan: 199 bytes\n- In other countries: String (252)\n\nFor Mastercard Transactions, Optionally Tag 9F60 (Authenticated Application Data) and \nTag 96 (Kernel Identifier - Terminal) can be included in the Field.\n\n#### GPX\nThis field only supports transactions from the following card types:\n- Visa\n- Mastercard\n- AMEX\n- Discover\n- Diners\n- JCB\n- Union Pay International\n\n#### JCN Gateway\nThe following tags must be included:\n- `4F`: Application identifier\n- `84`: Dedicated file name\n\nData length: 199 bytes\n\n#### All other processors:\nString (999)\n\n#### Used by\nAuthorization: Optional\nAuthorization Reversal: Optional\nCredit: Optional\nPIN Debit processing (purchase, credit and reversal): Optional\n"
paymentInformation:
type: object
properties:
paymentType:
type: object
properties:
method:
type: object
properties:
name:
type: string
description: 'Identifier for the payment type
'
merchantLimitedAcceptanceIndicator:
type: string
maxLength: 1
description: 'Mastercard One Credential merchant limited acceptance indicator. Mastercard One Credential connects multiple Mastercard payment methods and allows cardhollers to access various options and set payment preferences.
This field indicates which Mastercard One Credential funding PAN acceptance brands should NOT be assigned for this transaction.
This field flows in ISO field 34, DSID 02 tag DB, mapped to Mastercard Data Element (DE) 48, Sub element 02, Subfield 01.
Possible values:
- `C`: Do not assign a Mastercard One Credential funding PAN containing the Mastercard Credit Acceptance Brand for this transaction
- `D`: Do not assign a Mastercard One Credential funding PAN containing the Debit Mastercard Acceptance Brand for this transaction
- `M`: Do not assign a Mastercard One Credential funding PAN containing the Maestro Acceptance Brand for this transaction
This field is supported for Authorization reversal request.
#### Used by
**Authorization Reversal Request**
Optional field.
'
deviceInformation:
type: object
properties:
deviceType:
type: string
maxLength: 1
description: "Account Entry Device Type for Tap to More transactions. This field flows in ISO Field 34 DSID 02 Tag 89.\n\nValid Values:\n- `1`: Off-the-shelf mobile consumer\n\nMastercard is introducing changes to support commercialization of Tap to More transactions. \nAcquirers globally must be prepared to send a value of 1 (Off-the-shelf mobile-consumer) \nin Field 34—Acceptance Environment Data (TLV Format), Dataset ID 02—Acceptance Environment \nAdditional Data, Tag 89—Account Entry Device Type for Tap to More transactions. Visa will \nmap this value to a value of 8 (Remote terminal) in Mastercard Data Element 61.10.\n\n#### Mapping\n- SCMP API Field: customer_device_type\n- Simple Order API Field: billTo_deviceType\n- CCS: device.type\n- NRTF Key: customer_device_type\n\nOptional field.\n"
processorInformation:
type: object
properties:
preApprovalToken:
type: string
maxLength: 60
description: This is a token generated by PSP, which is received in response to the Sessions service. This token should be sent in the following transactions.
network:
type: object
properties:
economicallyRelatedTxnId:
type: string
maxLength: 50
description: Indicates the economically related transaction id
example:
clientReferenceInformation:
code: TC50171_3
transactionId: code
reversalInformation:
reason: testing
amountDetails:
totalAmount: '102.21'
responses:
'201':
description: Successful response.
schema:
title: ptsV2PaymentsReversalsPost201Response
type: object
properties:
_links:
type: object
properties:
self:
type: object
properties:
href:
type: string
description: This is the endpoint of the resource that was created by the successful request.
method:
type: string
description: '`method` refers to the HTTP method that you can send to the `self` endpoint to retrieve details of the resource.'
id:
type: string
maxLength: 26
description: 'An unique identification number generated by Cybersource to identify the submitted request. Returned by all services.
It is also appended to the endpoint of the resource.
On incremental authorizations, this value with be the same as the identification number returned in the original authorization response.
'
submitTimeUtc:
type: string
description: 'Time of request in UTC. Format: `YYYY-MM-DDThh:mm:ssZ`
**Example** `2016-08-11T22:47:57Z` equals August 11, 2016, at 22:47:57 (10:47:57 p.m.).
The `T` separates the date and the time. The `Z` indicates UTC.
Returned by Cybersource for all services.
'
status:
type: string
description: "The status of the submitted transaction.\n\nPossible values:\n - REVERSED\n"
reconciliationId:
type: string
maxLength: 60
description: 'Reference number for the transaction.
Depending on how your Cybersource account is configured, this value could either be provided in the API request or generated by CyberSource.
The actual value used in the request to the processor is provided back to you by Cybersource in the response.
'
clientReferenceInformation:
type: object
properties:
code:
type: string
maxLength: 59
description: 'Merchant-generated order reference or tracking number. It is recommended that you send a unique value for each
transaction so that you can perform meaningful searches for the transaction.
#### Used by
**Authorization**
Required field.
#### PIN Debit
Requests for PIN debit reversals need to use the same merchant reference number that was used in the transaction that is being
reversed.
Required field for all PIN Debit requests (purchase, credit, and reversal).
#### FDC Nashville Global
Certain circumstances can cause the processor to truncate this value to 15 or 17 characters for Level II and Level III processing, which can cause a discrepancy between the value you submit and the value included in some processor reports.
'
submitLocalDateTime:
type: string
maxLength: 14
description: 'Date and time at your physical location.
Format: `YYYYMMDDhhmmss`, where YYYY = year, MM = month, DD = day, hh = hour, mm = minutes ss = seconds
#### PIN Debit
Optional field for PIN Debit purchase and credit requests.
'
ownerMerchantId:
type: string
description: 'Merchant ID that was used to create the subscription or customer profile for which the service was requested.
If your CyberSource account is enabled for Recurring Billing, this field is returned only if you are using
subscription sharing and if your merchant ID is in the same merchant ID pool as the owner merchant ID.
If your CyberSource account is enabled for Payment Tokenization, this field is returned only if you are using
profile sharing and if your merchant ID is in the same merchant ID pool as the owner merchant ID.
'
reversalAmountDetails:
type: object
properties:
reversedAmount:
type: string
maxLength: 15
description: 'Total reversed amount.
Returned by authorization reversal.
'
originalTransactionAmount:
type: string
maxLength: 15
description: 'Amount of the original transaction.
Returned by authorization reversal and void.
'
currency:
type: string
maxLength: 3
description: 'Currency used for the order. Use the three-character [ISO Standard Currency Codes.](http://apps.cybersource.com/library/documentation/sbc/quickref/currencies.pdf)
#### Used by
**Authorization**
Required field.
# --- truncated at 32 KB (114 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/cybersource/refs/heads/main/openapi/cybersource-reversal-api-openapi.yml