CyberSource refund API
A refund is a follow-on transaction that uses the ID returned from either a payment or capture request.
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 refund API
host: apitest.cybersource.com
basePath: /
schemes:
- https
consumes:
- application/json;charset=utf-8
produces:
- application/hal+json;charset=utf-8
tags:
- name: refund
description: 'A refund is a follow-on transaction that uses the ID returned from either a payment or capture request.
'
paths:
/pts/v2/payments/{id}/refunds:
post:
summary: Refund a Payment
description: 'Refund a Payment API is only used, if you have requested Authorization and Capture together in [/pts/v2/payments](https://developer.cybersource.com/api-reference-assets/index.html#payments_payments) API call. Include the payment ID in the POST request to refund the payment amount.
'
tags:
- refund
operationId: refundPayment
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: refundPaymentRequest
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.
'
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.
'
returnReconciliationId:
type: string
description: A new ID which is created for refund
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.
'
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.
'
comments:
type: string
description: Brief description of the order or any comment you wish to add to the order.
partner:
type: object
properties:
originalTransactionId:
type: string
maxLength: 32
description: 'Value that links the previous transaction to the current follow-on request. This value is assigned by the client
software that is installed on the POS terminal, which makes it available to the terminal''s software and to
CyberSource. Therefore, you can use this value to reconcile transactions between CyberSource and the terminal''s
software.
CyberSource does not forward this value to the processor. Instead, the value is forwarded to the CyberSource
reporting functionality.
This field is supported only on these processors:
- American Express Direct
- Credit Mutuel-CIC
- FDC Nashville Global
- OmniPay Direct
- SIX
Optional field.
'
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.
'
processingInformation:
type: object
properties:
actionList:
type: array
description: "Array of actions (one or more) to be included in the payment to invoke bundled services along with payment status.\n\nPossible values are one or more of follows:\n\n - `AP_REFUND`: Use this when Alternative Payment Refund service is requested.\n"
items:
type: string
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.
'
purchaseLevel:
type: string
maxLength: 1
description: Set this field to 3 to indicate that the request includes Level III data.
recurringOptions:
type: object
properties:
loanPayment:
type: boolean
description: 'Flag that indicates whether this is a payment towards an existing contractual loan.
Possible values:
- `true`: Loan payment
- `false`: (default) Not a loan payment
'
default: false
industryDataType:
type: string
maxLength: 20
description: 'Indicates that the transaction includes industry-specific data.
Possible Values:
- `airline`
- `restaurant`
- `lodging`
- `auto_rental`
- `transit`
- `healthcare_medical`
- `healthcare_transit`
- `transit`
#### Card Present, Airlines and Auto Rental
You must set this field to `airline` in order for airline data to be sent to the processor. For example, if this
field is not set to `airline` or is not included in the request, no airline data is sent to the processor.
You must set this field to `restaurant` in order for restaurant data to be sent to the processor. When this field
is not set to `restaurant` or is not included in the request, no restaurant data is sent to the processor.
You must set this field to `auto_rental` in order for auto rental data to be sent to the processor. For example, if this
field is not set to `auto_rental` or is not included in the request, no auto rental data is sent to the processor.
Restaurant data is supported only on CyberSource through VisaNet.
'
paymentType:
type: string
description: Identifier for the payment type
refundOptions:
type: object
properties:
reason:
type: string
description: The reason for the refund.
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
'
merchantVerificationValue:
type: string
maxLength: 25
description: 'The override value of the Merchant Verification Value (MVV) received by various card brands. MVV refers to the value assigned by the card brand/network to identify participation in select merchant programs.
Sample value for Visa: `101010`
'
paymentInformation:
type: object
properties:
card:
type: object
properties:
number:
type: string
maxLength: 20
description: 'The customer''s payment card number, also known as the Primary Account Number (PAN). You can also use this field
for encoded account numbers.
#### FDMS Nashville
Required. String (19)
#### GPX
Required if `pointOfSaleInformation.entryMode=keyed`. However, this field is optional if your account is configured
for relaxed requirements for address data and expiration date. **Important** It is your responsibility to determine
whether a field is required for the transaction you are requesting.
#### All other processors
Required if `pointOfSaleInformation.entryMode=keyed`. However, this field is optional if your account is configured
for relaxed requirements for address data and expiration date. **Important** It is your responsibility to determine
whether a field is required for the transaction you are requesting.
'
expirationMonth:
type: string
maxLength: 2
description: 'Two-digit month in which the payment card expires.
Format: `MM`.
Valid values: `01` through `12`. Leading 0 is required.
#### Barclays and Streamline
For Maestro (UK Domestic) and Maestro (International) cards on Barclays and Streamline, this must be a valid value
(`01` through `12`) but is not required to be a valid expiration date. In other words, an expiration date that is
in the past does not cause CyberSource to reject your request. However, an invalid expiration date might cause
the issuer to reject your request.
#### Encoded Account Numbers
For encoded account numbers (_type_=039), if there is no expiration date on the card, use `12`.
#### FDMS Nashville
Required field.
#### All other processors
Required if `pointOfSaleInformation.entryMode=keyed`. However, this field is optional if your account is configured
for relaxed requirements for address data and expiration date. **Important** It is your responsibility to determine
whether a field is required for the transaction you are requesting.
#### Google Pay transactions
For PAN-based Google Pay transactions, this field is returned in the API response.
'
expirationYear:
type: string
maxLength: 4
description: 'Four-digit year in which the payment card expires.
Format: `YYYY`.
#### Barclays and Streamline
For Maestro (UK Domestic) and Maestro (International) cards on Barclays and Streamline, this must be a valid value (`1900` through `3000`) but is not required to be a valid expiration date. In other words, an expiration date that is in the past does not cause CyberSource to reject your request. However, an invalid expiration date might cause the issuer to reject your request.
#### Encoded Account Numbers
For encoded account numbers (**_type_**`=039`), if there is no expiration date on the card, use `2021`.
#### FDMS Nashville
Required field.
#### FDC Nashville Global and FDMS South
You can send in 2 digits or 4 digits. If you send in 2 digits, they must be the last 2 digits of the year.
#### All other processors
Required if `pointOfSaleInformation.entryMode=keyed`. However, this field is optional if your account is configured
for relaxed requirements for address data and expiration date. **Important** It is your responsibility to determine
whether a field is required for the transaction you are requesting.
#### Google Pay transactions
For PAN-based Google Pay transactions, this field is returned in the API response.
'
type:
type: string
description: 'Three-digit value that indicates the card type.
**IMPORTANT** It is strongly recommended that you include the card type field in request messages even if it is
optional for your processor and card type. Omitting the card type can cause the transaction to be processed with the wrong card type.
Possible values:
- `001`: Visa. Use card type value `001` for Visa Electron.
- `002`: Mastercard, Eurocard[^1], which is a European regional brand of Mastercard.
- `003`: American Express
- `004`: Discover
- `005`: Diners Club
- `006`: Carte Blanche[^1]
- `007`: JCB[^1]
- `008`: Optima
- `009`: GE Private Label
- `010`: Beneficial Private Label
- `011`: Twinpay Credit Card
- `012`: Twinpay Debit Card
- `013`: WalMart
- `014`: Enroute[^1]
- `015`: Lowe''s Consumer
- `016`: Home Depot Consumer
- `017`: MBNA
- `018`: Dick''s Sportswear
- `019`: Casual Corner
- `020`: Sears
- `021`: JAL[^1]
- `023`: Disney Card
- `024`: Maestro (UK Domestic)[^1]
- `025`: Sam''s Club Consumer
- `026`: Sam''s Club Business
- `027`: Nico''s
- `028`: Paymentech Bill Me Later
- `029`: Bebe
- `030`: Restoration Hardware
- `031`: Delta Online
- `032`: Solo
- `033`: Visa Electron[^1]. Do not use this value. Use `001` for all Visa card types.
- `034`: Dankort[^1]
- `035`: Laser
- `036`: Cartes Bancaires[^1,4]
- `037`: Carta Si[^1]
- `038`: Pinless Debit
- `039`: Encoded account number[^1]
- `040`: UATP[^1]
- `041`: HOUSEHOLD
- `042`: Maestro (International)[^1]
- `043`: GE MONEY
- `044`: Korean Cards
- `045`: Style Cards
- `046`: JCrew
- `047`: Payeasecn eWallet
- `048`: Payeasecn Bank Transfer
- `049`: Meijer
- `050`: Hipercard[^2,3]
- `051`: Aura
- `052`: Redecard
- `053`: Orico card
- `054`: Elo[^3]
- `055`: Capitol One Private Label
- `056`: Carnet
- `057`: Costco Private Label
- `058`: Carnet
- `059`: ValueLink
- `060`: MADA
- `061`: RuPay
- `062`: China UnionPay
- `063`: Falabella Private Label
- `064`: Prompt Card
- `065`: Korean Domestic
- `066`: Banricompras
- `067`: MEEZA
- `068`: PayPak
- `070`: EFTPOS
- `071`: Codensa
- `072`: Olimpica
- `073`: Colsubsidio
- `074`: Tuya
- `075`: Sodexo
- `076`: Naranja
- `077`: Cabal
- `078`: DINELCO
- `079`: PANAL
- `080`: EPM
- `081`: Jaywan
[^1]: For this card type, you must include the `paymentInformation.card.type` or `paymentInformation.tokenizedCard.type` field in your request for an authorization or a stand-alone credit.
[^2]: For this card type on Cielo 3.0, you must include the `paymentInformation.card.type` or `paymentInformation.tokenizedCard.type` field in a request for an authorization or a stand-alone credit. This card type is not supported on Cielo 1.5.
[^3]: For this card type on Getnet and Rede, you must include the `paymentInformation.card.type` or `paymentInformation.tokenizedCard.type` field in a request for an authorization or a stand-alone credit.
[^4]: For this card type, you must include the `paymentInformation.card.type` in your request for any payer authentication services.
#### Used by
**Authorization**
Required for Carte Blanche and JCB.
Optional for all other card types.
#### Card Present reply
This field is included in the reply message when the client software that is installed on the POS terminal uses
the token management service (TMS) to retrieve tokenized payment details. You must contact customer support to
have your account enabled to receive these fields in the credit reply message.
Returned by the Credit service.
This reply field is only supported by the following processors:
- American Express Direct
- Credit Mutuel-CIC
- FDC Nashville Global
- OmniPay Direct
- SIX
#### Google Pay transactions
For PAN-based Google Pay transactions, this field is returned in the API response.
#### GPX
This field only supports transactions from the following card types:
- Visa
- Mastercard
- AMEX
- Discover
- Diners
- JCB
- Union Pay International
'
accountEncoderId:
type: string
maxLength: 3
description: 'Identifier for the issuing bank that provided the customer''s encoded account number. Contact your processor for the bank''s ID.
'
issueNumber:
type: string
maxLength: 5
description: 'Number of times a Maestro (UK Domestic) card has been issued to the account holder. The card might or might not have an issue number. The number can consist of one or two digits, and the first digit might be a zero. When you include this value in your request, include exactly what is printed on the card. A value of 2 is different than a value of 02. Do not include the field, even with a blank value, if the card is not a Maestro (UK Domestic) card.
**Note** The issue number is not required for Maestro (UK Domestic) transactions.
'
startMonth:
type: string
maxLength: 2
description: 'Month of the start of the Maestro (UK Domestic) card validity period. Do not include the field, even with a blank value, if the card is not a Maestro (UK Domestic) card. `Format: MM`. Possible values: 01 through 12.
**Note** The start date is not required for Maestro (UK Domestic) transactions.
'
startYear:
type: string
maxLength: 4
description: 'Year of the start of the Maestro (UK Domestic) card validity period. Do not include the field, even with a blank value, if the card is not a Maestro (UK Domestic) card. `Format: YYYY`.
**Note** The start date is not required for Maestro (UK Domestic) transactions.
'
sourceAccountType:
type: string
maxLength: 20
description: "Flag that specifies the type of account associated with the card. \nThe cardholder provides this information during the payment process.\n\nThis field is required in the following cases:\n - Debit transactions on Cielo and Comercio Latino.\n - Transactions with Brazilian-issued cards on CyberSource through VisaNet.\n - Applicable only for CyberSource through VisaNet (CtV).\n\n**Note** Combo cards in Brazil contain credit and debit functionality in a single card. Visa systems use a credit bank\nidentification number (BIN) for this type of card. Using the BIN to determine whether a card is debit or\ncredit can cause transactions with these cards to be processed incorrectly. CyberSource strongly recommends\nthat you include this field for combo card transactions.\n\nPossible values include the following.\n\n - `CH`: Checking account\n - `CR`: Credit card account\n - `SA`: Saving account\n - `LI`: Line of credit or credit portion of combo card\n - `PP`: Prepaid card account or prepaid portion of combo card\n - `UA`: Universal account\n\nIf useAs is set to credit/debit and there is a value in SourceAccountType, the value in the SourceAccountType field will take precedence.\nIf useAs is set to CR/DB and there is a value in SourceAccountType, the value in the useAs field will take precedence.\n"
sourceAccountTypeDetails:
type: string
maxLength: 4
description: 'Type of account that is being used when the value for the override_payment_method field is line of credit (LI) or prepaid card (PP).
Possible values for line of credit:
- `AGRC`: Visa Agro Custeio
- `AGRE`: Visa Agro Electron
- `AGRI`: Visa Agro Investimento
- `AGRO`: Visa Agro
Possible values for prepaid card:
- `VVA`: Visa Vale Alimentacao
- `VVF`: Visa Vale Flex
- `VVR`: Visa Vale Refeicao
This field is supp
# --- truncated at 32 KB (559 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/cybersource/refs/heads/main/openapi/cybersource-refund-api-openapi.yml