CyberSource refund API
A refund is a follow-on transaction that uses the ID returned from either a payment or capture request.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/cybersource-refund-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.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
servers:
- url: https://apitest.cybersource.com/
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: id
in: path
description: The payment ID. This ID is returned from a previous payment request.
required: true
schema:
type: string
responses:
'201':
description: Successful response.
content:
application/hal+json;charset=utf-8:
schema:
title: ptsV2PaymentsRefundPost201Response
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.'
void:
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 - PENDING\n - DECLINED\n - INVALID_REQUEST\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.
'
returnReconciliationId:
type: string
description: A new ID which is created for refund
refundAmountDetails:
type: object
properties:
refundAmount:
type: string
maxLength: 15
description: Total amount of the refund.
creditAmount:
type: string
maxLength: 15
description: 'Amount that was credited to the cardholder''s account.
Returned by PIN debit credit.
'
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.
'
processingInformation:
type: object
properties:
enhancedDataEnabled:
type: boolean
description: 'The possible values for the reply field are:
- `true` : the airline data was included in the request to the processor.
- `false` : the airline data was not included in the request to the processor.
Returned by authorization, capture, or credit services.
'
processorInformation:
type: object
properties:
approvalCode:
type: string
maxLength: 6
description: 'Authorization code. Returned only when the processor returns this value.
The length of this value depends on your processor.
Returned by authorization service.
#### PIN debit
Authorization code that is returned by the processor.
Returned by PIN debit credit.
#### Elavon Encrypted Account Number Program
The returned value is OFFLINE.
#### TSYS Acquiring Solutions
The returned value for a successful zero amount authorization is 000000.
'
transactionId:
type: string
maxLength: 255
description: 'Network transaction identifier (TID). You can use this value to identify a specific transaction when you are
discussing the transaction with your processor. Not all processors provide this value.
Returned by the authorization service.
#### PIN debit
Transaction identifier generated by the processor.
Returned by PIN debit credit.
#### GPX
Processor transaction ID.
#### Cielo
For Cielo, this value is the non-sequential unit (NSU) and is supported for all transactions. The value is generated by Cielo or the issuing bank.
#### Comercio Latino
For Comercio Latino, this value is the proof of sale or non-sequential unit (NSU) number generated by the acquirers Cielo and Rede, or the issuing bank.
#### CyberSource through VisaNet and GPN
For details about this value for CyberSource through VisaNet and GPN, see "processorInformation.networkTransactionId" in [REST API Fields](https://developer.cybersource.com/content/dam/docs/cybs/en-us/apifields/reference/all/rest/api-fields.pdf)
#### Moneris
This value identifies the transaction on a host system. It contains the following information:
- Terminal used to process the transaction
- Shift during which the transaction took place
- Batch number
- Transaction number within the batch
You must store this value. If you give the customer a receipt, display this value on the receipt.
**Example** For the value
66012345001069003:
- Terminal ID = 66012345
- Shift number = 001
- Batch number = 069
- Transaction number = 003
'
forwardedAcquirerCode:
type: string
maxLength: 32
description: 'Name of the Japanese acquirer that processed the transaction. Returned only for JCN Gateway.
Please contact the CyberSource Japan Support Group for more information.
'
merchantNumber:
type: string
maxLength: 15
description: 'Identifier that was assigned to you by your acquirer. This value must be printed on the receipt.
#### Returned by
Authorizations and Credits.
This reply field is only supported by merchants who have installed client software on their POS terminals and
use these processors:
- American Express Direct
- Credit Mutuel-CIC
- FDC Nashville Global
- OmniPay Direct
- SIX
'
responseCode:
type: string
maxLength: 10
description: 'For most processors, this is the error message sent directly from the bank. Returned only when the processor
returns this value.
**Important** Do not use this field to evaluate the result of the authorization.
#### PIN debit
Response value that is returned by the processor or bank.
**Important** Do not use this field to evaluate the results of the transaction request.
Returned by PIN debit credit, PIN debit purchase, and PIN debit reversal.
#### AIBMS
If this value is `08`, you can accept the transaction if the customer provides you with identification.
#### Atos
This value is the response code sent from Atos and it might also include the response code from the bank.
Format: `aa,bb` with the two values separated by a comma and where:
- `aa` is the two-digit error message from Atos.
- `bb` is the optional two-digit error message from the bank.
#### Comercio Latino
This value is the status code and the error or response code received from the processor separated by a colon.
Format: [status code]:E[error code] or [status code]:R[response code]
Example `2:R06`
#### JCN Gateway
Processor-defined detail error code. The associated response category code is in the `processorInformation.responseCategoryCode` field.
String (3)
#### paypalgateway
Processor generated ID for the itemized detail.
'
responseSourceCode:
type: string
maxLength: 1
description: 'This field is used by Visa only and contains the response source/reason code that identifies the source of the
field 39 response decision. Use this field only for clearing with your acquirer.
'
achVerification:
type: object
properties:
resultCode:
type: string
maxLength: 2
description: 'Results from the ACH verification service.
'
resultCodeRaw:
type: string
maxLength: 10
description: 'Raw results from the ACH verification service.
'
networkTransactionId:
type: string
description: Same value as `processorInformation.transactionId`
settlementDate:
type: string
maxLength: 4
description: 'Field contains a settlement date. The date is in mmdd format, where: mm = month and dd = day.
'
updateTimeUtc:
type: string
description: 'The date and time when the transaction was last updated, in Internet date and time format.
'
network:
type: object
properties:
economicallyRelatedTxnId:
type: string
maxLength: 50
description: Indicates the economically related transaction id
merchantAdvice:
type: object
properties:
code:
type: string
maxLength: 2
description: "- Merchant should update their retry logic to ensure retry is not attempted for the cards for which Issuer won't approve the transactions and where the retry is allowed.\n- Card Processing Associations provides this data which is being passed through in the following data element irrespective of the Card Associations. Usage of this data must be always associated with the Card Associations card types for merchant processing retry logic.\n- In additions to the Merchant Advice code, Associations also provides the decline response codes which provides the reason for decline. Association response code will be a pass-through value.\n\n#### Processors supported:\n - HSBC\n - Barclays\n - FDC Nash\n - FDI Global\n - Elavon America\n - VPC\n - Rede\n - Payment tech Salem\n\n\n#### Possible values:\n| Card Type | Advice Code | Description |\n| ----------- | ------------- | ------------------------------------------- |\n| VISA | 1 | Issuer never approves |\n| VISA | 2 | Issuer cannot approve at this time |\n| VISA | 3 | Data quality/revalidate payment information |\n| MasterCard | 01 | New account information available |\n| MasterCard | 02 | Try Again Later |\n| MasterCard | 03 | Do Not Try Again |\n| MasterCard | 04 | Token not supported |\n| MasterCard | 21 | Do not honor |\n| MasterCard | 22 | Merchant does not qualify for product code |\n| MasterCard | 24 | Retry after 1 hour |\n| MasterCard | 25 | Retry after 24 hours |\n| MasterCard | 26 | Retry after 2 days |\n| MasterCard | 27 | Retry after 4 days |\n| MasterCard | 28 | Retry after 6 days |\n| MasterCard | 29 | Retry after 8 days |\n| MasterCard | 30 | Retry after 10 days |\n| MasterCard | 40 | Consumer non-reloadable prepaid card |\n| MasterCard | 41 | Consumer single-use virtual card number |\n| MasterCard | 42 | Sanctions score exceeds threshold value |\n| MasterCard | 99 | Do Not Try Again |\n\n#### Possbile values for Barclays processor:\n- 00: No information, or response not provided.\n- 01: New account information available\n- 02: Try again later\n- 03: Do not try again\n- 05: Payment blocked by the payment card company\n"
codeRaw:
type: string
maxLength: 4
description: 'Raw merchant advice code sent directly from the processor. This field is used only for Mastercard.
#### CyberSource through VisaNet
The value for this field corresponds to the following data in the TC 33 capture file1:
- Record: CP01 TCR7
- Position: 96-99
- Field: Response Data-Merchant Advice Code
#### Possbile values for Barclays processor:
- 01: Updated/additional information needed
- 02: Cannot approve at this time; try again later
- 04: Do not try again
- 08: Payment blocked by card scheme
'
orderInformation:
type: object
properties:
amountDetails:
type: object
properties:
cashbackAmount:
type: string
maxLength: 12
description: "This field contains the purchase cashback amount expressed in the acquirer transaction currency. \nUse this field only for clearing with your acquirer.\n"
settlementAmount:
type: string
maxLength: 12
description: 'This is a multicurrency field. It contains the transaction amount (field 4), converted to the Currency used to bill the cardholder''s account.
This field is returned for OCT transactions.
'
settlementCurrency:
type: string
maxLength: 3
description: 'This is a multicurrency-only field. It contains a 3-digit numeric code that identifies the currency used by the issuer to bill the cardholder''s account.
This field is returned for OCT transactions.
'
exchangeRate:
type: string
maxLength: 13
description: 'Exchange rate returned by the DCC service. Includes a decimal point and a maximum of 4 decimal places.
'
foreignAmount:
type: string
maxLength: 15
description: 'Set this field to the converted amount that was returned by the DCC provider.
'
foreignCurrency:
type: string
maxLength: 5
description: 'Set this field to the converted amount that was returned by the DCC provider.
'
invoiceDetails:
type: object
properties:
level3TransmissionStatus:
type: string
description: 'Indicates whether CyberSource sent the Level III information to the processor. The possible values are:
If your account is not enabled for Level III data or if you did not include the purchasing level field in your
request, CyberSource does not include the Level III data in the request sent to the processor.
Possible values:
- **Y** for true
- **N** for false
'
pointOfSaleInformation:
type: object
properties:
terminalId:
type: string
maxLength: 8
description: "Identifier for the terminal at your retail location. You can define this value yourself, but consult the processor for requirements.\n\n#### CyberSource through VisaNet\nA list of all possible values is stored in your CyberSource account. If terminal ID validation is enabled for\nyour CyberSource account, the value you send for this field is validated against the list each time you include\nthe field in a request. To enable or disable terminal ID validation, contact CyberSource Customer Support.\n\nWhen you do not include this field in a request, CyberSource uses the default value that is defined in your CyberSource account.\n\n#### FDC Nashville Global\nTo have your account configured to support this field, contact CyberSource Customer Support. This value must be a value that FDC Nashville Global issued to you.\n\n#### For Payouts\nThis field is applicable for CyberSource through VisaNet.\n\n#### GPX\nIdentifier for the terminal at your retail location. A list of all possible values is stored in your account.\nIf terminal ID validation is enabled for your account, the value you send for this field is validated against\nthe list each time you include the field in a request. To enable or disable terminal ID validation, contact\ncustomer support.\n\nWhen you do not include this field in a request, the default value that is defined in your account is used.\n\nOptional for authorizations.\n\n#### Used by\n**Authorization**\nOptional for the following processors. When you do not include this field in a request, the default value that is\ndefined in your account is used.\n - American Express Direct\n - Credit Mutuel-CIC\n - FDC Nashville Global\n - SIX\n- Chase Paymentech Solutions: Optional field. If you include this field in your request, you must also include `pointOfSaleInformation.catLevel`.\n- FDMS Nashville: The default value that is defined in your account is used.\n- GPX\n- OmniPay Direct: Optional field.\n\nFor the following processors, this field is not used.\n- GPN\n- JCN Gateway\n- RBS WorldPay Atlanta\n- TSYS Acquiring Solutions\n- Worldpay VAP\n\n#### Card Present reply\nTerminal identifier assigned by the acquirer. This value must be printed on the receipt.\n"
encryptedKeyId:
type: string
maxLength: 100
description: "Identifies the Zone PIN Key (ZPK) used for Online PIN processing by providing the 10‑digit Key Set Identifier (KSI).\nThis value indicates that the PIN block is encrypted under a ZPK and enables the Payment Security Service (PSS) to perform \nthe correct ZPK→ZPK PIN translation during card‑present EMV PIN transactions.\n"
errorInformation:
type: object
properties:
reason:
type: string
description: "The reason of the status.\n\nPossible values:\n - AVS_FAILED\n - CONTACT_PROCESSOR\n - EXPIRED_CARD\n - PROCESSOR_DECLINED\n - INSUFFICIENT_FUND\n - STOLEN_LOST_CARD\n - ISSUER_UNAVAILABLE\n - UNAUTHORIZED_CARD\n - CVN_NOT_MATCH\n - EXCEEDS_CREDIT_LIMIT\n - INVALID_CVN\n - BLOCKED_BY_CARDHOLDER\n - DECLINED_CHECK\n - BLACKLISTED_CUSTOMER\n - SUSPENDED_ACCOUNT\n - PAYMENT_REFUSED\n - CV_FAILED\n - INVALID_ACCOUNT\n - GENERAL_DECLINE\n - INVALID_MERCHANT_CONFIGURATION\n - DECISION_PROFILE_REJECT\n - SCORE_EXCEEDS_THRESHOLD\n - PENDING_AUTHENTICATION\n - ACH_VERIFICATION_FAILED\n - DECISION_PROFILE_REVIEW\n - CONSUMER_AUTHENTICATION_REQUIRED\n - CONSUMER_AUTHENTICATION_FAILED\n - ALLOWABLE_PIN_RETRIES_EXCEEDED\n - PROCESSOR_ERROR\n - CUSTOMER_WATCHLIST_MATCH\n - ADDRESS_COUNTRY_WATCHLIST_MATCH\n - EMAIL_COUNTRY_WATCHLIST_MATCH\n - IP_COUNTRY_WATCHLIST_MATCH\n - DAGGREJECTED\n - DAGGDENIED\n - DSYSREJECTED\n"
message:
type: string
description: The detail message related to the status and reason listed above.
details:
type: array
items:
type: object
properties:
field:
type: string
description: This is the flattened JSON object field name/path that is either missing or invalid.
reason:
type: string
description: "Possible reasons for the error.\n\nPossible values:\n - MISSING_FIELD\n - INVALID_DATA\n"
example:
_links:
self:
href: /pts/v2/refunds/4963014779006178301545
method: GET
void:
href: /pts/v2/refunds/4963014779006178301545/voids
method: POST
id: '4963014779006178301545'
submitTimeUtc: 2017-06-01T071757Z
status: '200'
reconciliationId: 39571012D3DFEKS0
statusInformation:
reason: SUCCESS
message: Successful transaction.
clientReferenceInformation:
code: Testing-VDP-Payments-Refund
orderInformation:
amountDetails:
currency: USD
refundAmountDetails:
currency: USD
refundAmount: '102.21'
'400':
description: Invalid request.
content:
application/hal+json;charset=utf-8:
schema:
type: object
title: ptsV2PaymentsRefundPost400Response
properties:
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
# --- truncated at 32 KB (592 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/cybersource/refs/heads/main/openapi/cybersource-refund-api-openapi.yml