CyberSource capture API
When you are ready to fulfill a customer's order and transfer funds from the customer's bank to your bank, capture the payment for that order.
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 capture API
host: apitest.cybersource.com
basePath: /
schemes:
- https
consumes:
- application/json;charset=utf-8
produces:
- application/hal+json;charset=utf-8
tags:
- name: capture
description: 'When you are ready to fulfill a customer''s order and transfer funds from the customer''s
bank to your bank, capture the payment for that order.
'
paths:
/pts/v2/payments/{id}/captures:
post:
summary: Capture a Payment
description: Include the payment ID in the POST request to capture the payment amount.
tags:
- capture
operationId: capturePayment
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: capturePaymentRequest
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.
'
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:
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.
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.
'
digitalServiceIndicator:
type: string
maxLength: 104
description: "Mastercard Digital Enablement Service (MDES) digital service indicators for force capture scenarios. \n\nThis field is used when the client is doing authorization with a different gateway and capture with CyberSource. \n\nThis field is in ANS, EBCDIC format and flows in Field 34, DSID 04 Tag DF1F, mapped to Mastercard Data Element DE119, Sub-element 004.\n\n#### Used by\n**Capture Request**\nRequest field for force capture support when auth is done with a different gateway.\n"
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**.
'
authorizationOptions:
type: object
properties:
authType:
type: string
maxLength: 15
description: "Authorization type. Possible values:\n\n - `AUTOCAPTURE`: automatic capture.\n - `STANDARDCAPTURE`: standard capture.\n - `VERBAL`: forced capture. Include it in the payment request for a forced capture. Include it in the capture request for a verbal payment.\n\n#### Asia, Middle East, and Africa Gateway; Cielo; Comercio Latino; and CyberSource Latin American Processing\nSet this field to `AUTOCAPTURE` and include it in a bundled request to indicate that you are requesting an automatic capture. If your account is configured to enable automatic captures, set this field to `STANDARDCAPTURE` and include it in a standard authorization or bundled request to indicate that you are overriding an automatic capture.\n\n#### Forced Capture\nSet this field to `VERBAL` and include it in the authorization request to indicate that you are performing a forced capture; therefore, you receive the authorization code outside the CyberSource system.\n\n#### Verbal Authorization\nSet this field to `VERBAL` and include it in the capture request to indicate that the request is for a verbal authorization.\n\n#### for PayPal ptsV2CreateOrderPost400Response\nSet this field to 'AUTHORIZE' or 'CAPTURE' depending on whether you want to invoke delayed capture or sale respectively.\n"
verbalAuthCode:
type: string
maxLength: 7
description: 'Authorization code.
#### Forced Capture
Use this field to send the authorization code you received from a payment that you authorized
outside the CyberSource system.
#### PIN debit
Authorization code that is returned by the processor.
Returned by PIN debit purchase.
#### Verbal Authorization
Use this field in CAPTURE API to send the verbally received authorization code.
'
verbalAuthTransactionId:
type: string
maxLength: 15
description: 'Transaction ID (TID).
#### FDMS South
This field is required for verbal authorizations and forced captures with the American Express card type to comply
with the CAPN requirements:
- Forced capture: Obtain the value for this field from the authorization response.
- Verbal authorization: You cannot obtain a value for this field so CyberSource uses the default value of `000000000000000` (15
zeros).
'
captureOptions:
type: object
properties:
captureSequenceNumber:
type: integer
minimum: 1
maximum: 99
description: "Capture number when requesting multiple partial captures for one authorization.\nUsed along with `totalCaptureCount` to track which capture is being processed.\n\nFor example, the second of five captures would be passed to CyberSource as:\n - `captureSequenceNumber_ = 2`, and\n - `totalCaptureCount = 5`\n"
totalCaptureCount:
type: integer
minimum: 1
maximum: 99
description: "Total number of captures when requesting multiple partial captures for one payment.\nUsed along with `captureSequenceNumber` field to track which capture is being processed.\n\nFor example, the second of five captures would be passed to CyberSource as:\n - `captureSequenceNumber = 2`, and\n - `totalCaptureCount = 5`\n"
isFinal:
type: string
maxLength: 5
description: "Indicates whether to release the authorization hold on the remaining funds. \nPossible Values:\n- `true`\n- `false`\n"
notes:
type: string
maxLength: 255
description: 'An informational note about this settlement. Appears in both the payer''s transaction history and the emails that the payer receives.
'
reconciliationIdAlternate:
type: string
maxLength: 12
description: Used by Nike merchant to send 12 digit order number
loanOptions:
type: object
properties:
type:
type: string
maxLength: 20
description: 'Type of loan based on an agreement between you and the issuer.
Examples: AGROCUSTEIO, AGRO-INVEST, BNDES-Type1, CBN, FINAME.
This field is supported only for these kinds of payments:
- BNDES transactions on CyberSource through VisaNet.
- Installment payments with Mastercard on CyberSource through VisaNet in Brazil.
For BNDES transactions, the value for this field corresponds to the following data in the TC 33 capture file:
- Record: CP07 TCR2, Position: 27-46, Field: Loan Type
For installment payments with Mastercard in Brazil, the value for this field corresponds to the following data in the TC 33 capture file:
- Record: CP07 TCR4, Position: 5-24,Field: Financing Type
'
assetType:
type: string
maxLength: 1
description: "Indicates whether a loan is for a recoverable item or a non-recoverable item.\nPossible values:\n- `N`: non-recoverable item\n- `R`: recoverable item\nThis field is supported only for BNDES transactions on CyberSource through VisaNet.\nThe value for this field corresponds to the following data in the TC 33 capture file5:\n Record: CP07 TCR2, Position: 26, Field: Asset Indicator\n"
payByPointsIndicator:
type: boolean
description: 'Flag that indicates if the transaction is pay by points transaction
true: Transaction uses loyalty points
false: Transaction does not use loyalty points
Default: false
'
actionList:
type: array
description: "Array of actions (one or more) to be included in the capture to invoke bundled services along with capture.\n\nPossible values :\n\n - `AP_CAPTURE`: Use this when Alternative Payment Capture service is requested.\n"
items:
type: string
japanPaymentOptions:
type: object
properties:
paymentMethod:
type: string
maxLength: 2
description: 'This value is a 2-digit code indicating the payment method.
Use Payment Method Code value that applies to the tranasction.
- 10 (One-time payment)
- 21, 22, 23, 24 (Bonus(one-time)payment)
- 61 (Installment payment)
- 31, 32, 33, 34 (Integrated (Bonus + Installment)payment)
- 80 (Revolving payment)
'
bonuses:
type: string
maxLength: 2
description: 'Field contains the number of bonuses.
'
installments:
type: string
maximum: 99
description: 'Number of Installments.
'
firstBillingMonth:
type: string
maxLength: 2
description: 'Billing month in MM format.
'
bonusAmount:
type: string
maxLength: 12
description: 'This field contains the bonus amount.
'
bonusMonth:
type: string
maxLength: 2
description: 'This field contains the Japan specific first bonus month.
'
secondBonusAmount:
type: string
maxLength: 12
description: 'Field contains the second bonus amount.
'
secondBonusMonth:
type: string
maxLength: 2
description: 'Field contains the Japan specific second bonus month.
'
paymentInformation:
type: object
properties:
customer:
type: object
properties:
customerId:
type: string
description: 'Unique identifier for the customer''s card and billing information.
When you use Payment Tokenization or Recurring Billing and you include this value in
your request, many of the fields that are normally required for an authorization or credit
become optional.
**NOTE** When you use Payment Tokenization or Recurring Billing, the value for the Customer ID is actually the Cybersource payment token for a customer. This token stores information such as the consumer''s card number so it can be applied towards bill payments, recurring payments, or one-time payments. By using this token in a payment API request, the merchant doesn''t need to pass in data such as the card number or expiration date in the request itself.
'
id:
type: string
description: 'Unique identifier for the Customer token used in the transaction.
When you include this value in your request, many of the fields that are normally required for an authorization or credit
become optional.
'
minLength: 1
maxLength: 32
card:
type: object
properties:
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 supported only for combo card transactions in Brazil on CyberSource through VisaNet.
'
paymentType:
type: object
properties:
method:
type: object
properties:
name:
type: string
description: 'A Payment Type is enabled through a Method. Examples: Visa, Master Card, ApplePay, iDeal, 7Eleven, alfamart, bofaPayByBank, payToPayByBank, etc
For Japan Payment Processing Valid Values:
- 1 Banking Data
- 2 Authorization Data
#### Via KCP
- `KCP` : Local Card, Bank Transfer and Carrier Billing.
- `PAYCO`
- `KAKAOPAY`
- `NAVERPAY`
'
orderInformation:
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.
'
discountAmount:
type: string
maxLength: 15
description: 'Total discount amount applied to the order.
'
dutyAmount:
type: string
maxLength: 15
description: 'Total charges for any import or export duties included in the order.
'
gratuityAmount:
type: string
maxLength: 13
de
# --- truncated at 32 KB (287 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/cybersource/refs/heads/main/openapi/cybersource-capture-api-openapi.yml