CyberSource capture API

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 Capture API
servers:
- url: https://apitest.cybersource.com/
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: id
        in: path
        description: 'The payment ID returned from a previous payment request. This ID links the capture to the payment.

          '
        required: true
        schema:
          type: string
      responses:
        '201':
          description: Successful response.
          content:
            application/hal+json;charset=utf-8:
              schema:
                title: ptsV2PaymentsCapturesPost201Response
                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.'
                      refund:
                        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 - TRANSMITTED (Only for Online Capture enabled merchants)\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.

                          '
                  processorInformation:
                    type: object
                    properties:
                      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

                          '
                      networkTransactionId:
                        type: string
                        description: Same value as `processorInformation.transactionId`
                      responseDetails:
                        type: string
                        maxLength: 60
                        description: 'The processor code that describes why the transaction state is pending or reversed.

                          '
                      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.

                          '
                      providerResponse:
                        type: string
                        description: 'Processor response to the API request.

                          '
                      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
                  orderInformation:
                    type: object
                    properties:
                      amountDetails:
                        type: object
                        properties:
                          totalAmount:
                            type: string
                            maxLength: 15
                            description: 'Amount you requested for the capture.

                              '
                          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.

                              '
                          processorTransactionFee:
                            type: string
                            maxLength: 15
                            description: The fee decided by the PSP/Processor per transaction.
                      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"
                  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.

                          '
                  embeddedActions:
                    type: object
                    properties:
                      ap_capture:
                        type: object
                        properties:
                          reason:
                            type: string
                            description: "The reason why the captured payment status is PENDING or DENIED.\nBUYER_COMPLAINT\tThe payer initiated a dispute for this captured payment with processor.\nCHARGEBACK\tThe captured funds were reversed in response to the payer disputing this captured payment with the issuer of the financial instrument used to pay for this captured payment.\nECHECK\tThe payer paid by an eCheck that has not yet cleared.\nINTERNATIONAL_WITHDRAWAL\tVisit your online account. In your Account Overview, accept and deny this payment.\nOTHER\tNo additional specific reason can be provided. For more information about this captured payment, visit your account online or contact processor.\nPENDING_REVIEW\tThe captured payment is pending manual review.\nRECEIVING_PREFERENCE_MANDATES_MANUAL_ACTION\tThe payee has not yet set up appropriate receiving preferences for their account. For more information about how to accept or deny this payment, visit your account online. This reason is typically offered in scenarios such as when the currency of the captured payment is different from the primary holding currency of the payee.\nREFUNDED\tThe captured funds were refunded.\nTRANSACTION_APPROVED_AWAITING_FUNDING\tThe payer must send the funds for this captured payment. This code generally appears for manual EFTs.\nUNILATERAL\tThe payee does not have a processor account.\nVERIFICATION_REQUIRED\tThe payee's processor account is not verified.\nString with values,\n `BUYER_COMPLAINT`\n `CHARGEBACK`\n `ECHECK`\n `INTERNATIONAL_WITHDRAWAL`\n `OTHER`\n `PENDING_REVIEW`\n `RECEIVING_PREFERENCE_MANDATES_MANUAL_ACTION`\n `REFUNDED`\n `TRANSACTION_APPROVED_AWAITING_FUNDING`\n `UNILATERAL`\n `VERIFICATION_REQUIRED`\n"
                example:
                  _links:
                    self:
                      href: /pts/v2/captures/4963014519526177701545
                      method: GET
                    refund:
                      href: /pts/v2/captures/4963014519526177701545/refunds
                      method: POST
                    void:
                      href: /pts/v2/captures/4963014519526177701545/voids
                      method: POST
                  id: '4963014519526177701545'
                  submitTimeUtc: 2017-06-01T071731Z
                  status: '200'
                  reconciliationId: 39570715X3E1LBQA
                  statusInformation:
                    reason: SUCCESS
                    message: Successful transaction.
                  clientReferenceInformation:
                    code: TC50171_3
                  orderInformation:
                    amountDetails:
                      totalAmount: '102.21'
                      currency: USD
        '400':
          description: Invalid request.
          content:
            application/hal+json;charset=utf-8:
              schema:
                type: object
                title: ptsV2PaymentsCapturesPost400Response
                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:
                    type: string
                    description: "The status of the submitted transaction.\n\nPossible values:\n - INVALID_REQUEST\n"
                  reason:
                    type: string
                    description: "The reason of the status.\n\nPossible values:\n - MISSING_FIELD\n - INVALID_DATA\n - DUPLICATE_REQUEST\n - INVALID_MERCHANT_CONFIGURATION\n - EXCEEDS_AUTH_AMOUNT\n - AUTH_ALREADY_REVERSED\n - TRANSACTION_ALREADY_SETTLED\n - INVALID_AMOUNT\n - MISSING_AUTH\n - TRANSACTION_ALREADY_REVERSED_OR_SETTLED\n - NOT_SUPPORTED\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"
        '502':
          description: Unexpected system error or system timeout.
          content:
            application/hal+json;charset=utf-8:
              schema:
                title: ptsV2PaymentsCapturesPost502Response
                type: object
                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:
                    type: string
                    description: "The status of the submitted transaction.\n\nPossible values:\n - SERVER_ERROR\n"
                  reason:
                    type: string
                    description: "The reason of the status.\n\nPossible values:\n - SYSTEM_ERROR\n - SERVER_TIMEOUT\n - SERVICE_TIMEOUT\n"
                  message:
                    type: string
                    description: The detail message related to the status and reason listed above.
      x-example:
        example0:
          summary: Capture a Payment
          value:
            clientReferenceInformation:
              code: TC50171_3
            orderInformation:
              amountDetails:
                totalAmount: '102.21'
                currency: USD
          depends:
            example:
              path: /pts/v2/payments
              verb: post
              exampleId: example0
            fieldMapping:
            - sourceField: id
              destinationField: id
              fieldTypeInDestination: path
        example1:
          summary: Capture a Payment - Service Fee
          value:
            clientReferenceInformation:
              code: TC50171_3
            orderInformation:
              amountDetails:
                totalAmount: '2325.00'
                currency: USD
                serviceFeeAmount: '30.0'
            merchantInformation:
              serviceFeeDescriptor:
                name: Vacations Service Fee
                contact: 8009999999
                state: CA
          depends:
            example:
              path: /pts/v2/payments
              verb: post
              exampleId: example14
            fieldMapping:
            - sourceField: id
              destinationField: id
              fieldTypeInDestination: path
        example2:
          summary: Capture of Authorization that used Swiped track data
          sample-name: Capture of Authorization that used Swiped track data
          value:
            clientReferenceInformation:
              code: '1234567890'
              partner:
                thirdPartyCertificationNumber: '123456789012'
            orderInformation:
              amountDetails:
                totalAmount: 100
                currency: USD
          parentTag: Card Present with Visa Platform Connect
        example3:
          summary: Restaurant Capture with Gratuity
          sample-name: Restaurant Capture with Gratuity
          value:
            clientReferenceInformation:
              code: 1234567890
              partner:
                thirdPartyCertificationNumber: 123456789012
            processingInformation:
              industryDataType: restaurant
            orderInformation:
              amountDetails:
                totalAmount: 100
                currency: USD
                gratuityAmount: '11.50'
          parentTag: Card Present with Visa Platform Connect
      requestBody:
        content:
          application/json;charset=utf-8:
            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:
  

# --- truncated at 32 KB (303 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/cybersource/refs/heads/main/openapi/cybersource-capture-api-openapi.yml