A payment authorizes the amount for the transaction. There are a number of supported payment instruments, such as Credit Card, Debit Card, e-Wallet, and Alternative Payments. A payment response includes the status of the request. It also includes processor-specific information when the request is successful and errors if unsuccessful.
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 payments API
host: apitest.cybersource.com
basePath: /
schemes:
- https
consumes:
- application/json;charset=utf-8
produces:
- application/hal+json;charset=utf-8
tags:
- name: payments
description: 'A payment authorizes the amount for the transaction. There are a number of supported payment
instruments, such as Credit Card, Debit Card, e-Wallet, and Alternative Payments. A payment
response includes the status of the request. It also includes processor-specific information
when the request is successful and errors if unsuccessful.
'
paths:
/pts/v2/payments:
post:
summary: Process a Payment
description: 'A payment authorizes the amount for the transaction. There are a number of supported payment features, such as E-commerce and Card Present - Credit Card/Debit Card, Echeck, e-Wallets, Level II/III Data, etc..
A payment response includes the status of the request. It also includes processor-specific information when the request is successful and errors if unsuccessful. See the [Payments Developer Guides Page](https://developer.cybersource.com/docs/cybs/en-us/payments/developer/ctv/rest/payments/payments-intro.html).
Authorization can be requested with Capture, Decision Manager, Payer Authentication(3ds), and Token Creation.
'
tags:
- payments
operationId: createPayment
produces:
- application/hal+json;charset=utf-8
consumes:
- application/json;charset=utf-8
x-devcenter-metaData:
categoryTag: Payments
testingTriggers: https://developer.cybersource.com/hello-world/testing-guide.html
responseCodes: https://developer.cybersource.com/api/reference/response-codes.html
developerGuides: https://developer.cybersource.com/docs/cybs/en-us/payments/developer/ctv/rest/payments/payments-intro.html
isMLEsupported: true
mleForRequest: optional
parameters:
- name: createPaymentRequest
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:
actionList:
type: array
description: "Array of actions (one or more) to be included in the payment to invoke bundled services along with payment.\n\nPossible values are one or more of follows:\n\n - `DECISION_SKIP`: Use this when you want to skip Decision Manager service(s).\n\n - `TOKEN_CREATE`: Use this when you want to create a token from the card/bank data in your payment request.\n\n - `CONSUMER_AUTHENTICATION`: Use this when you want to check if a card is enrolled in Payer Authentication along with your payment request.\n\n - `VALIDATE_CONSUMER_AUTHENTICATION`: Use this after you acquire a Payer Authentication result that needs to be included for your payment request.\n \n - `AP_INITIATE`: Use this when Alternative Payment Initiate service is requested.\n\n - `WATCHLIST_SCREENING` : Use this when you want to call Watchlist Screening service.\n\n - `AP_SALE` : Use this when Alternative Payment Sale service is requested.\n\n\n - `AP_AUTH` : Use this when Alternative Payment Authorize service is requested.\n\n - `AP_REAUTH` : Use this when Alternative Payment Reauthorize service is requested.\n"
items:
type: string
enableEscrowOption:
type: boolean
description: "Indicates whether to use the customer's escrow agreement.\nPossible values:\n- `true`: yes, use the customer's escrow agreement.\n- `false`: no, do not use the customer's escrow agreement. \n"
actionTokenTypes:
type: array
description: 'CyberSource tokens types you are performing a create on.
If not supplied the default token type for the merchants token vault will be used.
Valid values:
- customer
- paymentInstrument
- instrumentIdentifier
- shippingAddress
'
items:
type: string
binSource:
type: string
description: 'Bin Source File Identifier.
Possible values:
- itmx
- rupay
'
capture:
type: boolean
description: 'Indicates whether to also include a capture in the submitted authorization request or not.
Possible values:
- `true`: Include a capture with an authorization request.
- `false`: (default) Do not include a capture with an authorization request.
#### Used by
**Authorization and Capture**
Optional field.
'
default: false
processorId:
type: string
maxLength: 3
description: 'Value that identifies the processor/acquirer to use for the transaction. This value is supported only for
**CyberSource through VisaNet**.
Contact CyberSource Customer Support to get the value for this field.
'
businessApplicationId:
type: string
description: "Required for AFT and OCT transactions.\n\nGiven below is a list of all the BAI values available. However, the processors may support only few specific BAI values.\n\n- AA : Account-to-account \n- BB : Supplier Payments\n- BI : Bank-Initiated P2P Money Transfer\n- BP : Non-Card Bill Pay/Bill Pay\n- CD : Cash Deposit\n- CP : Credit card Bill Payment\n- FD : Funds disbursement \n- FT : Funds transfer\n- GD : Government Disbursement\n- GP : Gambling payout (non-online gambling)\n- LO : Loyalty credits and rebates\n- MD : Merchant Settlement\n- OG : Online Gambling Payout\n- PD : Payroll and pension disbursement\n- PP : Person-to-Person or Peer-to-Peer\n- TU : Top up, prepaid load\n- WT : Digital wallet \n"
commerceIndicator:
type: string
maxLength: 20
description: "Type of transaction. Some payment card companies use this information when determining discount rates.\n\n#### Used by\n**Authorization**\nRequired payer authentication transactions; otherwise, optional.\n**Credit**\nRequired for standalone credits on Chase Paymentech solutions; otherwise, optional.\n\nThe list of valid values in this field depends on your processor.\n\n#### Ingenico ePayments\nWhen you omit this field for Ingenico ePayments, the processor uses the default transaction type they have on file for you instead of the default value \n\n#### Card Present\nYou must set this field to `retail`. This field is required for a card-present transaction. Note that this should ONLY be\nused when the cardholder and card are present at the time of the transaction.\nFor all keyed transactions originated from a POS terminal where the cardholder and card are not present, commerceIndicator\nshould be submitted as \"moto\"\n"
commerceIndicatorLabel:
type: string
maxLength: 20
description: "Type of transaction. Some payment card companies use this information when determining discount rates.\n\n#### Used by\n**Authorization**\nRequired payer authentication transactions; otherwise, optional.\n**Credit**\nRequired for standalone credits on Chase Paymentech solutions; otherwise, optional.\n\nThe list of valid values in this field depends on your processor.\n\n#### Ingenico ePayments\nWhen you omit this field for Ingenico ePayments, the processor uses the default transaction type they have on file for you\ninstead of the default value \n\n#### Card Present\nYou must set this field to `retail`. This field is required for a card-present transaction. Note that this should ONLY be\nused when the cardholder and card are present at the time of the transaction.\nFor all keyed transactions originated from a POS terminal where the cardholder and card are not present, commerceIndicator\nshould be submitted as `moto`\n"
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
'
purchaseLevel:
type: string
maxLength: 1
description: Set this field to 3 to indicate that the request includes Level III data.
transactionTimeout:
type: integer
maximum: 99999
description: The time-out limit in seconds for the transaction. The time-out limit starts when the customer is directed to the merchant URL that is included in the sale service response. The maximum value is 99999 (about 27 hours). When the transaction times out, the payment system changes the status to abandoned.
intentsId:
type: string
maxLength: 26
description: Set to the value of the requestID field returned in the order service response.
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.
'
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.
'
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"
panReturnIndicator:
type: string
maxLength: 1
description: '#### Visa Platform Connect
The field contains the PAN translation indicator for American Express Contactless Transaction. Valid value is
1- Expresspay Translation, PAN request
2- Expresspay Translation, PAN and Expiry date request
'
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).
'
authIndicator:
type: string
maxLength: 1
description: "Flag that specifies the purpose of the authorization.\n\nPossible values:\n - **0**: Preauthorization\n - **1**: Final authorization\n\nTo set the default for this field, contact CyberSource Customer Support.\n\n#### Barclays and Elavon\nThe default for Barclays and Elavon is 1 (final authorization). To change the default for this field, contact CyberSource Customer Support.\n\n#### CyberSource through VisaNet\nWhen the value for this field is 0, it corresponds to the following data in the TC 33 capture file:\n - Record: CP01 TCR0\n - Position: 164\n - Field: Additional Authorization Indicators\nWhen the value for this field is 1, it does not correspond to any data in the TC 33 capture file.\n"
partialAuthIndicator:
type: boolean
description: 'Flag that indicates whether the transaction is enabled for partial authorization. When the request includes this
field, this value overrides the information in your account. Possible values:
- `true`: Enable the transaction for partial authorization.
- `false`: Do not enable the transaction for partial authorization.
#### PIN debit
Required field for partial authorizations that use PIN debit purchase; otherwise, not used.
#### Used by
**Authorization**
Optional field.
#### CyberSource through VisaNet
To set the default for this field, contact CyberSource Customer Support.
The value for this field corresponds to the following data in the TC 33 capture file5:
- Record: CP01 TCR0
- Position: 164
- Field: Additional Authorization Indicators
'
extendAuthIndicator:
type: string
maxLength: 5
description: "Indicates Authorization extension transaction. Extension transaction is used to prolong the settlement period by one additional settlement cycle period.\n\nPossible values:\n- true: Transaction is an Authorization Extension transaction. \n- false: Transaction is not an Authorization Extension transaction.\n"
balanceInquiry:
type: boolean
description: 'Flag that indicates whether to return balance information.
Possible values:
- `true`: Return balance information.
- `false`: Do not return balance information.
#### Used by
**Authorization**
Required for a balance inquiry; otherwise, not used.
#### PIN debit
Required for a balance inquiry request of a PIN debit purchase; otherwise, not used.
'
ignoreAvsResult:
type: boolean
description: 'Flag for a sale request that indicates whether to allow the capture service to run even when the authorization
receives an AVS decline, as indicated by a reply flag value of DAVSNO.
Possible values:
- `true`: Ignore the results of AVS checking and run the capture service.
- `false` (default): If the authorization receives an AVS decline, do not run the capture service.
When the value of this field is `true`, the list in the `processingInformation.authorizationOptions.declineAvsFlags` field is ignored.
#### Used by
**Authorization**
Optional field.
String (3)
'
default: false
declineAvsFlags:
type: array
description: "Comma-separated list of AVS flags that cause the reply flag `DAVSNO` to be returned.\n\n**Important** To receive declines for the AVS code `N`, you must include the value `N` in the comma-separated\nlist.\n\n ### AVS Codes for Cielo 3.0 and CyberSource Latin American Processing\n\n **Note** CyberSource Latin American Processing is the name of a specific processing connection that CyberSource supports.\n In the CyberSource API documentation, CyberSource Latin American Processing does not refer to the general topic of processing in Latin America.\n The information in this section is for the specific processing connection called CyberSource Latin American Processing.\n It is not for any other Latin American processors that CyberSource supports.\n\n|AVS Code|Description|\n|--- |--- |\n|D|Partial match: postal code and address match.|\n|E|Not supported: AVS is not supported for this card type. _or_ Invalid: the acquirer returned an unrecognized value for the AVS response.|\n|F|Partial match: postal code matches, but CPF and address do not match.*|\n|G|Not supported: AVS not supported or not verified.|\n|I|No match: AVS information is not available.|\n|K|Partial match: CPF matches, but postal code and address do not match.*|\n|L|Partial match: postal code and CPF match, but address does not match.*|\n|N|No match: postal code, CPF, and address do not match.*|\n|O|Partial match: CPF and address match, but postal code does not match.*|\n|R|Not supported: your implementation does not support AVS _or_ System unavailable.|\n|T|Partial match: address matches, but postal code and CPF do not match.*|\n|V|Match: postal code, CPF, and address match.*|\n|* CPF (Cadastro de Pessoas Fisicas) is required only for Redecard in Brazil.||\n\n### AVS Codes for All Other Processors\n\n**Note** The list of AVS codes for all other processors follows these descriptions of the processor-specific information for these codes.\n\n#### American Express Cards\nFor American Express cards only, you can receive Visa and CyberSource\nAVS codes in addition to the American Express AVS codes.\n\n**Note** For CyberSource through VisaNet, the American Express AVS codes are converted to Visa\nAVS codes before they are returned to you. As a result, you will not receive American Express AVS codes for\nthe American Express card type.<br/><br/>\n\n_American Express Card codes_: `F`, `H`, `K`, `L`, `O`, `T`, `V`\n\n#### Domestic and International Visa Cards\nThe international and domestic alphabetic AVS codes are the Visa standard AVS codes. CyberSource maps\nthe standard AVS return codes for other types of payment cards, including American Express cards, to\nthe Visa standard AVS codes.\n\nAVS is considered either domestic or international, depending on the location of the bank that issued the\ncustomer's payment card:\n- When the bank is in the U.S., the AVS is domestic.\n- When the bank is outside the U.S., the AVS is international.\n\nYou should be prepared to handle both domestic and international AVS result codes:\n- For international cards, you can receive domestic AVS codes in addition to the international AVS codes.\n- For domestic cards, you can receive international AVS codes in addition to the domestic AVS codes.\n\n_International Visa Codes_: `B`, `C`, `D`, `G`, `I`, `M`, `P`\n\n_Domestic Visa Codes_: `A`, `E`,`N`, `R`, `S`, `U`, `W`, `X`, `Y`, `Z`\n\n#### CyberSource Codes\nThe numeric AVS codes are created by CyberSource\nand are not standard Visa codes. These AVS codes\ncan be returned for any card type.\n\n_CyberSource Codes_: `1`, `2`, `3`, `4`\n\n### Table of AVS Codes for All Other Processors\n\n|AVS Code|Description|\n|--- |--- |\n|A|Partial match: street address matches, but 5-digit and 9-digit postal codes do not match.|\n|B|Partial match: street address matches, but postal code is not verified. Returned only for Visa cards not issued in the U.S.|\n|C|No match: street address and postal code do not match. Returned only for Visa cards not issued in the U.S.|\n|D & M|Match: street address and postal code match. Returned only for Visa cards not issued in the U.S.|\n|E|Invalid: AVS data is invalid or AVS is not allowed for this card type.|\n|F|Partial match: card member's name does not match, but billing postal code matches.|\n|G|Not supported: issuing bank outside the U.S. does not support AVS.|\n|H|Partial match: card member's name does not match, but street address and postal code match. Returned only for the American Express card type.|\n|I|No match: address not verified. Returned only for
# --- truncated at 32 KB (1564 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/cybersource/refs/heads/main/openapi/cybersource-payments-api-openapi.yml