> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.payroc.com/llms.txt. > For full documentation content, see https://docs.payroc.com/llms-full.txt. # Capture the pre-authorization If your merchant doesn't capture a pre-authorization, it expires and the issuing bank releases the hold on the customer's card. To capture the pre-authorization, you must use our API. ## Before you begin ### Bearer tokens Use our Identity Service to generate a Bearer token to include in the header of your requests. To generate your Bearer token, complete the following steps: 1. Include your API key in the x-api-key parameter in the header of a POST request. 2. Send your request to [https://identity.payroc.com/authorize](https://identity.payroc.com/authorize). **Note:** You need to generate a new Bearer token before the previous Bearer token expires. **Example request** ```bash curl --location --request POST 'https://identity.payroc.com/authorize' --header 'x-api-key: ' ``` **Example response**\ If your request is successful, we return a response that contains your Bearer token, information about its scope, and when it expires. ```json { "access_token": "eyJhbGc....adQssw5c", "expires_in": 3600, "scope": "service_a service_b", "token_type": "Bearer" } ``` ### Headers To create the header of each POST request, you must include the following parameters: * **Content-Type:** Include application/json as the value for this parameter. * **Authorization:** Include your Bearer token in this parameter. * **Idempotency-Key:** Include a UUID v4 to make the request idempotent. ```bash curl -H "Content-Type: application/json" -H "Authorization: " -H "Idempotency-Key: " ``` ### Errors If your request is unsuccessful, we return an error. For more information about errors, see [Errors](/api/errors). ## Send a POST request to capture the pre-authorization To capture the pre-authorization, you need the UNIQUEREF that we returned to the merchant's receipt page. Send the UNIQUEREF in the paymentId path parameter in a POST request to our Payments endpoint. | Environment | Prefix | URL | | :---------- | :------- | :--------------------------------------------------------------------------------------------------------------------- | | Test | api.uat. | [https://api.uat.payroc.com/v1/payments/:paymentId/capture](https://api.uat.payroc.com/v1/payments/:paymentId/capture) | | Production | api. | [https://api.payroc.com/v1/payments/:paymentId/capture](https://api.payroc.com/v1/payments/:paymentId/capture) | Depending on the amount you want to capture: * **Capture the full amount of the pre-authorization** - Don’t send a value for the amount parameter in your request. * **Capture less than the amount of the pre-authorization** - Send a value for the amount parameter in your request. * **Capture more than the amount of the pre-authorization** - Adjust the pre-authorization before you capture it. For more information about adjusting a pre-authorization, go to [Adjust Payment](https://docs.payroc.com/api/schema/card-payments/payments/adjust). ### Request parameters To create the body of your request, use the following parameters: ### Schema (`request.body`) ```yaml openapi: 3.1.0 info: title: API version: 1.0.0 paths: /payments/{paymentId}/capture: post: operationId: capture summary: Capture payment description: "Use this method to capture a pre-authorization. \n\nTo capture a pre-authorization, you need its paymentId. Our gateway returned the paymentId in the response of the [Create Payment](https://docs.payroc.com/api/schema/card-payments/payments/create) method.\n\n**Note:** If you don't have the paymentId, use our [List Payments](https://docs.payroc.com/api/schema/card-payments/payments/list) method to search for the payment.\n\nDepending on the amount you want to capture, complete the following:\n-\t**Capture the full amount of the pre-authorization** - Don't send a value for the amount parameter in your request.\n-\t**Capture less than the amount of the pre-authorization** - Send a value for the amount parameter in your request. \n-\t**Capture more than the amount of the pre-authorization** - Adjust the pre-authorization before you capture it. For more information about adjusting a pre-authorization, go to [Adjust Payment](https://docs.payroc.com/api/schema/card-payments/payments/adjust).\n\nIf your request is successful, our gateway takes the amount from the payment card. \n\n**Note:** For more information about pre-authorizations and captures, go to [Run a pre-authorization](https://docs.payroc.com/guides/integrate/run-a-pre-authorization).\n" tags: - subpackage_cardPayments.subpackage_cardPayments/payments parameters: - name: paymentId in: path description: >- Unique identifier of the payment that the merchant wants to retrieve. required: true schema: type: string - name: Idempotency-Key in: header description: >- Unique identifier that you generate for each request. You must use the [UUID v4 format](https://www.rfc-editor.org/rfc/rfc4122) for the identifier. For more information about the idempotency key, go to [Idempotency](https://docs.payroc.com/api/idempotency). required: true schema: type: string format: uuid responses: '200': description: Successful request. We captured the payment. content: application/json: schema: $ref: '#/components/schemas/payment' '400': description: Validation error content: application/json: schema: $ref: '#/components/schemas/400' '401': description: Identity could not be verified content: application/json: schema: $ref: '#/components/schemas/401' '403': description: Do not have permissions to perform this action content: application/json: schema: $ref: '#/components/schemas/403' '404': description: Resource not found content: application/json: schema: $ref: '#/components/schemas/404' '406': description: Not acceptable content: application/json: schema: $ref: '#/components/schemas/406' '409': description: Conflict content: application/json: schema: $ref: '#/components/schemas/409' '415': description: Unsupported media type content: application/json: schema: $ref: '#/components/schemas/415' '500': description: An error has occured content: application/json: schema: $ref: '#/components/schemas/500' requestBody: content: application/json: schema: $ref: '#/components/schemas/paymentCapture' servers: - url: https://api.payroc.com/v1 - url: https://api.uat.payroc.com/v1 components: schemas: '400': type: object properties: type: type: string description: URI reference identifying the problem type title: type: string description: Short description of the issue. status: type: integer description: Http status code detail: type: string description: Explanation of the problem errors: type: array items: $ref: '#/components/schemas/ErrorsItems' required: - type - title - status - detail title: '400' '401': type: object properties: type: type: string description: URI reference identifying the problem type title: type: string description: Short description of the issue. status: type: integer description: Http status code detail: type: string description: Explanation of the problem required: - type - title - status - detail title: '401' '403': type: object properties: type: type: string description: URI reference identifying the problem type title: type: string description: Short description of the issue. status: type: integer description: Http status code detail: type: string description: Explanation of the problem instance: type: string description: Resource path the action was attempted on resource: type: string description: Resource the action was attempted on required: - type - title - status - detail title: '403' '404': type: object properties: type: type: string description: URI reference identifying the problem type title: type: string description: Short description of the issue. status: type: integer description: Http status code detail: type: string description: Explanation of the problem resource: type: string description: Resource that was not found required: - type - title - status - detail title: '404' '406': type: object properties: type: type: string description: URI reference identifying the problem type title: type: string description: Short description of the issue. status: type: integer description: Http status code detail: type: string description: Explanation of the problem required: - type - title - status - detail title: '406' '409': type: object properties: type: type: string description: URI reference identifying the problem type title: type: string description: Short description of the issue. status: type: integer description: Http status code detail: type: string description: Explanation of the problem instance: type: string description: Resource path to the existing resource errors: type: array items: $ref: '#/components/schemas/ErrorsItems' link: $ref: '#/components/schemas/link' required: - type - title - status - detail title: '409' '415': type: object properties: type: type: string description: URI reference identifying the problem type title: type: string description: Short description of the issue. status: type: integer description: Http status code detail: type: string description: Explanation of the problem required: - type - title - status - detail title: '415' '500': type: object properties: type: type: string description: URI reference identifying the problem type title: type: string description: Short description of the issue. status: type: integer description: Http status code detail: type: string description: Explanation of the problem errors: type: array items: $ref: '#/components/schemas/ErrorsItems' required: - type - title - status - detail title: '500' TipType: type: string enum: - percentage - fixedAmount description: > Indicates if the tip is a fixed amount or a percentage. **Note:** Our gateway applies the percentage tip to the total amount of the transaction after tax. title: TipType TipMode: type: string enum: - prompted - adjusted description: > Indicates how the tip was added to the transaction. - `prompted` – The customer was prompted to add a tip during payment. - `adjusted` – The customer added a tip on the receipt for the merchant to adjust post-transaction. title: TipMode tip: type: object properties: type: $ref: '#/components/schemas/TipType' description: > Indicates if the tip is a fixed amount or a percentage. **Note:** Our gateway applies the percentage tip to the total amount of the transaction after tax. mode: $ref: '#/components/schemas/TipMode' description: > Indicates how the tip was added to the transaction. - `prompted` – The customer was prompted to add a tip during payment. - `adjusted` – The customer added a tip on the receipt for the merchant to adjust post-transaction. amount: type: integer format: int64 description: > If the value for type is `fixedAmount`, this value is the tip amount in the currency's lowest denomination, for example, cents. percentage: type: number format: double description: >- If the value for type is `percentage`, this value is the tip as a percentage. required: - type description: Object that contains information about the tip. title: tip surcharge: type: object properties: bypass: type: boolean description: > Indicates if the merchant wants to remove the surcharge fee from the transaction. - `true` - Gateway removes the surcharge fee from the transaction. - `false` - Gateway adds the fee to the transaction. amount: type: integer format: int64 description: > If the merchant added a surcharge fee, this value indicates the amount of the surcharge fee in the currency’s lowest denomination, for example, cents. percentage: type: number format: double description: >- If the merchant added a surcharge fee, this value indicates the surcharge percentage. description: | Object that contains information about the surcharge. title: surcharge choiceRate: type: object properties: applied: type: boolean default: false description: > Indicates if the merchant applies a choice rate to the transaction amount. Our gateway adds a choice rate to the transaction when the merchant offers an alternative payment type, but the customer chooses to pay by card. rate: type: number format: double description: > If the customer used a card to pay for the transaction, this value indicates the percentage that our gateway added to the transaction amount. **Note:** Our gateway returns a value for **rate** only if the value for **applied** in the request is `true`. amount: type: integer format: int64 description: > If the customer used a card to pay for the transaction, this value indicates the amount that our gateway added to the transaction amount. This value is in the currency’s lowest denomination, for example, cents. **Note:** Our gateway returns a value for **amount** only if the value for **applied** in the request is `true`. required: - applied - rate - amount description: > Object that contains information about the choice rate. We return this only if the value for offered was `true`. title: choiceRate DualPricingAlternativeTender: type: string enum: - card - cash - bankTransfer description: > Payment method that the merchant presented to the customer as an alternative to their chosen method. **Note:** For requests, if the value for **offered** is `true`, you must send a value for **alternativeTender** in the request. title: DualPricingAlternativeTender dualPricing: type: object properties: offered: type: boolean description: Indicates if the merchant offered dual pricing to the customer. choiceRate: $ref: '#/components/schemas/choiceRate' description: > Object that contains information about the choice rate. **Note:** For requests, if the value for **offered** is `true`, you must send this object in the request. alternativeTender: $ref: '#/components/schemas/DualPricingAlternativeTender' description: > Payment method that the merchant presented to the customer as an alternative to their chosen method. **Note:** For requests, if the value for **offered** is `true`, you must send a value for **alternativeTender** in the request. required: - offered description: Object that contains information about dual pricing. title: dualPricing tax: oneOf: - type: object properties: type: type: string enum: - amount description: 'Discriminator value: amount' amount: type: integer format: int64 description: >- Tax amount for the transaction. The value is in the currency's lowest denomination, for example, cents. name: type: string description: Name of the tax. required: - type - amount - name description: amount variant - type: object properties: type: type: string enum: - rate description: 'Discriminator value: rate' rate: type: number format: double description: Tax percentage for the transaction. name: type: string description: >- Name of the tax. A tax validation on the stored rate for the tax name is performed. required: - type - rate - name description: rate variant discriminator: propertyName: type description: "Polymorphic object that contains tax details. \n\nThe value of the type parameter determines which variant you should use: \n-\t`amount` - Tax is a fixed amount.\n-\t`rate` - Tax is a percentage.\n" title: tax convenienceFee: type: object properties: amount: type: integer format: int64 description: > If the merchant added a convenience fee, this value indicates the amount of the convenience fee in the currency’s lowest denomination, for example, cents. required: - amount description: >- Object that contains information about the convenience fee for the transaction. title: convenienceFee unitOfMeasure: type: string enum: - ACR - AMH - AMP - APZ - ARE - ASM - ASV - ATM - ATT - BAR - BFT - BHP - BHX - BIL - BLD - BLL - BQL - BTU - BUA - BUI - BX - CCT - CDL - CEL - CEN - CGM - CKG - CLF - CLT - CMK - CMT - CNP - CNT - COU - CS - CTM - CUR - CWA - DAA - DAD - DAY - DEC - DLT - DMK - DMQ - DMT - DPC - DPT - DRA - DRI - DRL - DRM - DTH - DTN - DWT - DZN - DZP - DZR - EA - EAC - FAH - FAR - FOT - FTK - FTQ - GBQ - GFI - GGR - GII - GLD - GLI - GLL - GRM - GRN - GRO - GRT - GWH - HAR - HBA - HGM - HIU - HLT - HMQ - HMT - HPA - HTZ - HUR - INH - INK - INQ - ITM - JOU - KBA - KEL - KGM - KGS - KHZ - KJO - KMH - KMK - KMQ - KMT - KNI - KNS - KNT - KPA - KPH - KPO - KPP - KSD - KSH - KTN - KUR - KVA - KVR - KVT - KWH - KWT - LBR - LBS - LEF - LPA - LTN - LTR - LUM - LUX - MAL - MAM - MAW - MBE - MBF - MBR - MCU - MGM - MHZ - MIK - MIL - MIN - MIO - MIU - MLD - MLT - MMK - MMQ - MMT - MON - MPA - MQH - MQS - MSK - MTK - MTQ - MTR - MTS - MVA - MWH - NAR - NBB - NCL - NEW - NIU - NMB - NMI - NMP - NMR - NPL - NPT - NRL - NTT - OHM - ONZ - OZA - OZI - PAL - PCB - PCE - PGL - PK - PSC - PTD - PTI - PTL - QAN - QTD - QTI - QTL - QTR - RPM - RPS - SAN - SCO - SCR - SEC - SET - SHT - SIE - SMI - SST - ST - STI - TAH - TNE - TPR - TQD - TRL - TSD - TSH - VLT - WCD - WEB - WEE - WHR - WSD - WTT - YDK - YDQ description: >- Unit of measurement for the item. For more information about units of measurement, go to [Units of measurement](https://docs.payroc.com/knowledge/basic-concepts/units-of-measurement). title: unitOfMeasure lineItemRequest: type: object properties: commodityCode: type: string description: Commodity code of the item. productCode: type: string description: Product code of the item. description: type: string description: Description of the item. unitOfMeasure: $ref: '#/components/schemas/unitOfMeasure' unitPrice: type: integer format: int64 description: Price of each unit. quantity: type: number format: double description: Number of units. discountRate: type: number format: double description: Discount rate that the merchant applies to the item. taxes: type: array items: $ref: '#/components/schemas/tax' description: >- Array of objects that contain information about each tax that applies to the item. required: - unitPrice - quantity description: List of line items. title: lineItemRequest itemizedBreakdownRequest: type: object properties: subtotal: type: integer format: int64 description: >- Amount of the transaction before tax and fees. The value is in the currency’s lowest denomination, for example, cents. cashbackAmount: type: integer format: int64 description: Amount of cashback for the transaction. tip: $ref: '#/components/schemas/tip' description: Object that contains tip information for the transaction. surcharge: $ref: '#/components/schemas/surcharge' description: Object that contains surcharge information for the transaction. dualPricing: $ref: '#/components/schemas/dualPricing' description: Object that contains dual pricing information for the transaction. taxes: type: array items: $ref: '#/components/schemas/tax' description: "Array of polymorphic tax objects, which contain information about a tax. \n\nThe value of the type parameter determines which variant you should use: \n-\t`amount` - Tax is a fixed amount.\n-\t`rate` - Tax is a percentage.\n" dutyAmount: type: integer format: int64 description: > Amount of duties or fees that apply to the order. The value is in the currency's lowest denomination, for example, cents. freightAmount: type: integer format: int64 description: > Amount for shipping in the currency's lowest denomination, for example, cents. convenienceFee: $ref: '#/components/schemas/convenienceFee' items: type: array items: $ref: '#/components/schemas/lineItemRequest' description: >- Array of objects that contain information about each item that the customer purchased. required: - subtotal description: Object that contains information about the breakdown of the transaction. title: itemizedBreakdownRequest paymentCapture: type: object properties: processingTerminalId: type: string description: Unique identifier that our gateway assigned to the terminal. operator: type: string description: Operator who captured the payment. amount: type: integer format: int64 description: > Amount that the merchant wants to capture. The value is in the currency's lowest denomination, for example, cents. **Note:** If the merchant does not send an amount, we capture the total amount of the transaction. breakdown: $ref: '#/components/schemas/itemizedBreakdownRequest' description: >- Object that contains the details of the payment that the merchant wants to capture. title: paymentCapture currency: type: string enum: - AED - AFN - ALL - AMD - ANG - AOA - ARS - AUD - AWG - AZN - BAM - BBD - BDT - BGN - BHD - BIF - BMD - BND - BOB - BOV - BRL - BSD - BTN - BWP - BYR - BZD - CAD - CDF - CHE - CHF - CHW - CLF - CLP - CNY - COP - COU - CRC - CUC - CUP - CVE - CZK - DJF - DKK - DOP - DZD - EGP - ERN - ETB - EUR - FJD - FKP - GBP - GEL - GHS - GIP - GMD - GNF - GTQ - GYD - HKD - HNL - HRK - HTG - HUF - IDR - ILS - INR - IQD - IRR - ISK - JMD - JOD - JPY - KES - KGS - KHR - KMF - KPW - KRW - KWD - KYD - KZT - LAK - LBP - LKR - LRD - LSL - LTL - LVL - LYD - MAD - MDL - MGA - MKD - MMK - MNT - MOP - MRO - MRU - MUR - MVR - MWK - MXN - MXV - MYR - MZN - NAD - NGN - NIO - NOK - NPR - NZD - OMR - PAB - PEN - PGK - PHP - PKR - PLN - PYG - QAR - RON - RSD - RUB - RWF - SAR - SBD - SCR - SDG - SEK - SGD - SHP - SLL - SOS - SRD - SSP - STD - STN - SVC - SYP - SZL - THB - TJS - TMT - TND - TOP - TRY - TTD - TWD - TZS - UAH - UGX - USD - USN - USS - UYI - UYU - UZS - VEF - VES - VND - VUV - WST - XAF - XCD - XOF - XPF - YER - ZAR - ZMW - ZWL description: >- Currency of the transaction. The value for the currency follows the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard. title: currency dccOffer: type: object properties: accepted: type: boolean description: Indicates if the cardholder accepted DCC offer. offerReference: type: string description: Unique identifier of the DCC offer. fxAmount: type: integer format: int64 description: >- Amount in the cardholder’s currency in the currency’s lowest denomination, for example, cents. fxCurrency: $ref: '#/components/schemas/currency' description: >- Currency of the transaction in the card’s currency. The value for the currency follows the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard. fxCurrencyCode: type: string description: >- Three-digit currency code for the card. This code follows the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard. fxCurrencyExponent: type: integer description: > Number of decimal places between the smallest currency unit and a whole currency unit. For example, for GBP, the smallest currency unit is 1p and it is equal to £0.01. If you use GBP, the value for **fxCurrencyExponent** is 2. fxRate: type: number format: double description: Foreign exchange rate for the card's currency. markup: type: number format: double description: >- Markup percentage rate that the DCC provider applies to the foreign exchange rate. markupText: type: string description: Supporting text for the markup rate. provider: type: string description: Name of the DCC provider. source: type: string description: Source that the DCC provider used to get the foreign exchange rates. required: - fxAmount - fxCurrency - fxRate - markup description: > Object that contains information about the dynamic currency conversion (DCC) offer. For more information about DCC, go to [Dynamic Currency Conversion](https://docs.payroc.com/knowledge/card-payments/dynamic-currency-conversion). title: dccOffer StandingInstructionsSequence: type: string enum: - first - subsequent description: Position of the transaction in the payment plan sequence. title: StandingInstructionsSequence StandingInstructionsProcessingModel: type: string enum: - unscheduled - recurring - installment description: > Indicates the type of payment instruction. - 'unscheduled' – The payment is not part of a regular billing cycle. - 'recurring' – The payment is part of a regular billing cycle with no end date. - 'installment' – The payment is part of a regular billing cycle with an end date. title: StandingInstructionsProcessingModel firstTxnReferenceData: type: object properties: paymentId: type: string description: > Unique identifier of the first payment. **Note:** We recommend that you always send a value for **paymentId**. cardSchemeReferenceId: type: string description: Identifier that the card brand assigns to the payment instruction. description: >- Object that contains information about the initial payment for the payment instruction. title: firstTxnReferenceData standingInstructions: type: object properties: sequence: $ref: '#/components/schemas/StandingInstructionsSequence' description: Position of the transaction in the payment plan sequence. processingModel: $ref: '#/components/schemas/StandingInstructionsProcessingModel' description: > Indicates the type of payment instruction. - 'unscheduled' – The payment is not part of a regular billing cycle. - 'recurring' – The payment is part of a regular billing cycle with no end date. - 'installment' – The payment is part of a regular billing cycle with an end date. referenceDataOfFirstTxn: $ref: '#/components/schemas/firstTxnReferenceData' description: >- Object that contains information about the initial payment for the payment instruction. required: - sequence - processingModel description: >- If you don't use our Subscriptions mechanism, include this section to configure your standing/recurring orders. title: standingInstructions retrievedTax: type: object properties: name: type: string description: Name of the tax. rate: type: number format: double description: Tax percentage for the transaction. amount: type: integer format: int64 description: >- Amount of tax that was applied to the transaction. The value is in the currency's lowest denomination, for example, cents. required: - name - rate title: retrievedTax lineItem: type: object properties: commodityCode: type: string description: Commodity code of the item. productCode: type: string description: Product code of the item. description: type: string description: Description of the item. unitOfMeasure: $ref: '#/components/schemas/unitOfMeasure' unitPrice: type: integer format: int64 description: Price of each unit. quantity: type: number format: double description: Number of units. discountRate: type: number format: double description: Discount rate that the merchant applies to the item. taxes: type: array items: $ref: '#/components/schemas/retrievedTax' description: >- Array of objects that contain information about each tax that applies to the item. required: - unitPrice - quantity description: List of line items. title: lineItem itemizedBreakdown: type: object properties: subtotal: type: integer format: int64 description: >- Amount of the transaction before tax and fees. The value is in the currency’s lowest denomination, for example, cents. cashbackAmount: type: integer format: int64 description: Amount of cashback for the transaction. tip: $ref: '#/components/schemas/tip' description: Object that contains tip information for the transaction. surcharge: $ref: '#/components/schemas/surcharge' description: Object that contains surcharge information for the transaction. dualPricing: $ref: '#/components/schemas/dualPricing' description: Object that contains dual pricing information for the transaction. taxes: type: array items: $ref: '#/components/schemas/retrievedTax' description: List of taxes. dutyAmount: type: integer format: int64 description: > Amount of duties or fees that apply to the order. The value is in the currency's lowest denomination, for example, cents. freightAmount: type: integer format: int64 description: > Amount for shipping in the currency's lowest denomination, for example, cents. convenienceFee: $ref: '#/components/schemas/convenienceFee' items: type: array items: $ref: '#/components/schemas/lineItem' description: >- Array of objects that contain information about each item that the customer purchased. required: - subtotal description: Object that contains information about the breakdown of the transaction. title: itemizedBreakdown paymentOrder: type: object properties: orderId: type: string description: A unique identifier assigned by the merchant. dateTime: type: string format: date-time description: >- Date and time that the processor processed the transaction. Our gateway returns this value in the ISO 8601 format. description: type: string description: Description of the transaction. amount: type: integer format: int64 description: >- Total amount of the transaction. The value is in the currency’s lowest denomination, for example, cents. currency: $ref: '#/components/schemas/currency' dccOffer: $ref: '#/components/schemas/dccOffer' standingInstructions: $ref: '#/components/schemas/standingInstructions' breakdown: $ref: '#/components/schemas/itemizedBreakdown' required: - orderId - amount - currency description: Object that contains information about the payment. title: paymentOrder retrievedAddress: type: object properties: address1: type: string description: Address line 1. address2: type: string description: Address line 2. address3: type: string description: Address line 3. city: type: string description: City. state: type: string description: Name of the state or state abbreviation. country: type: string description: >- Two-digit country code for the country that the business operates in. The format follows the [ISO-3166-1](https://www.iso.org/iso-3166-country-codes.html) standard. postalCode: type: string description: Zip code or postal code. description: Object that contains information about the address. title: retrievedAddress retrievedShipping: type: object properties: recipientName: type: string description: Recipient's name. address: $ref: '#/components/schemas/retrievedAddress' description: >- Object that contains information about the customer and their shipping address. title: retrievedShipping contactMethod: oneOf: - type: object properties: type: type: string enum: - email description: 'Discriminator value: email' value: type: string description: Email address. required: - type - value description: email variant - type: object properties: type: type: string enum: - phone description: 'Discriminator value: phone' value: type: string description: Phone number. required: - type - value description: phone variant - type: object properties: type: type: string enum: - mobile description: 'Discriminator value: mobile' value: type: string description: Mobile number. required: - type - value description: mobile variant - type: object properties: type: type: string enum: - fax description: 'Discriminator value: fax' value: type: string description: Fax number. required: - type - value description: fax variant discriminator: propertyName: type title: contactMethod RetrievedCustomerNotificationLanguage: type: string enum: - en - fr description: > Language that the customer uses for notifications. This code follows the [ISO 639-1](https://www.iso.org/iso-639-language-code) alpha-2 standard. title: RetrievedCustomerNotificationLanguage retrievedCustomer: type: object properties: firstName: type: string description: Customer's first name. lastName: type: string description: Customer's last name. dateOfBirth: type: string format: date description: >- Customer's date of birth. The format for this value is **YYYY-MM-DD**. referenceNumber: type: string description: > Identifier of the transaction, also known as a customer code. For requests, you must send a value for **referenceNumber** if the customer provides one. billingAddress: $ref: '#/components/schemas/retrievedAddress' description: >- Object that contains information about the address that the card is registered to. shippingAddress: $ref: '#/components/schemas/retrievedShipping' contactMethods: type: array items: $ref: '#/components/schemas/contactMethod' description: "Array of polymorphic objects, which contain contact information. \n\nThe value of the type parameter determines which variant you should use: \n-\t`email` - Email address \n-\t`phone` - Phone number\n-\t`mobile` - Mobile number\n-\t`fax` - Fax number\n" notificationLanguage: $ref: '#/components/schemas/RetrievedCustomerNotificationLanguage' description: > Language that the customer uses for notifications. This code follows the [ISO 639-1](https://www.iso.org/iso-639-language-code) alpha-2 standard. description: >- Object that contains the customer's contact details and address information. title: retrievedCustomer CardEntryMethod: type: string enum: - icc - keyed - swiped - swipedFallback - contactlessIcc - contactlessMsr description: Method that the device used to capture the card details. title: CardEntryMethod SecureTokenSummaryStatus: type: string enum: - notValidated - cvvValidated - validationFailed - issueNumberValidated - cardNumberValidated - bankAccountValidated description: > Status of the customer's bank account. The processor performs a security check on the customer's bank account and returns the status of the account. **Note:** Depending on the merchant's account settings, this feature may be unavailable. title: SecureTokenSummaryStatus link: type: object properties: rel: type: string description: >- Indicates the relationship between the current resource and the target resource. method: type: string description: HTTP method that you need to use with the target resource. href: type: string description: URL of the target resource. required: - rel - method - href description: Object that contains HATEOAS links for the resource. title: link secureTokenSummary: type: object properties: secureTokenId: type: string description: Unique identifier that the merchant assigned to the secure token. customerName: type: string description: Customer's name. token: type: string description: > Token that the merchant can use in future transactions to represent the customer's payment details. The token: - Begins with the six-digit identification number **296753**. - Contains up to 12 digits. - Contains a single check digit that we calculate using the Luhn algorithm. status: $ref: '#/components/schemas/SecureTokenSummaryStatus' description: > Status of the customer's bank account. The processor performs a security check on the customer's bank account and returns the status of the account. **Note:** Depending on the merchant's account settings, this feature may be unavailable. link: $ref: '#/components/schemas/link' required: - secureTokenId - customerName - token - status description: Object that contains information about the secure token. title: secureTokenSummary SecurityCheckCvvResult: type: string enum: - M - 'N' - P - U description: > Indicates if the card verification value (CVV) that the customer provided in the request matches the CVV on the card. - `M` – The CVV matches the card’s CVV. - `N` – The CVV doesn’t match the card’s CVV. - `P` – The CVV wasn’t processed. - `U` – The CVV isn’t registered. **Note:** Our gateway doesn’t automatically decline transactions when the CVV doesn’t match the card’s CVV, unless the merchant selects this setting in their account. title: SecurityCheckCvvResult SecurityCheckAvsResult: type: string enum: - 'Y' - A - Z - 'N' - U - R - G - S - F - W - X description: > Indicates if the address that the customer provided in the request matches the address linked to the card. - `Y` – The address in the request matches the address linked to the card. - `N` – The address in the request doesn’t match the address linked to the card. - `A` – The street address matches, but ZIP code or postal code doesn’t match. - `Z` - The ZIP code or postal code matches, but street address doesn’t match. - `U` – The address information is unavailable. - `G` – The issuer or card brand doesn’t support the Address Verification Service (AVS). - `R` – The AVS is currently unavailable. Try again later. - `S` – There was no AVS data in the request, or it was sent in the wrong format. - `F` - For UK addresses, the address in the request matches the address linked to the card. - `W` – For US addresses, the nine-digit ZIP code or postal code in the request matches the address linked to the card but the street address doesn’t. - `X` – For US addresses, the nine-digit ZIP code or postal code and the street address matches the address linked to the card. **Note:** Our gateway doesn’t automatically decline transactions when the address doesn’t match the address linked to the card, unless the merchant selects this setting in their account. title: SecurityCheckAvsResult securityCheck: type: object properties: cvvResult: $ref: '#/components/schemas/SecurityCheckCvvResult' description: > Indicates if the card verification value (CVV) that the customer provided in the request matches the CVV on the card. - `M` – The CVV matches the card’s CVV. - `N` – The CVV doesn’t match the card’s CVV. - `P` – The CVV wasn’t processed. - `U` – The CVV isn’t registered. **Note:** Our gateway doesn’t automatically decline transactions when the CVV doesn’t match the card’s CVV, unless the merchant selects this setting in their account. avsResult: $ref: '#/components/schemas/SecurityCheckAvsResult' description: > Indicates if the address that the customer provided in the request matches the address linked to the card. - `Y` – The address in the request matches the address linked to the card. - `N` – The address in the request doesn’t match the address linked to the card. - `A` – The street address matches, but ZIP code or postal code doesn’t match. - `Z` - The ZIP code or postal code matches, but street address doesn’t match. - `U` – The address information is unavailable. - `G` – The issuer or card brand doesn’t support the Address Verification Service (AVS). - `R` – The AVS is currently unavailable. Try again later. - `S` – There was no AVS data in the request, or it was sent in the wrong format. - `F` - For UK addresses, the address in the request matches the address linked to the card. - `W` – For US addresses, the nine-digit ZIP code or postal code in the request matches the address linked to the card but the street address doesn’t. - `X` – For US addresses, the nine-digit ZIP code or postal code and the street address matches the address linked to the card. **Note:** Our gateway doesn’t automatically decline transactions when the address doesn’t match the address linked to the card, unless the merchant selects this setting in their account. description: >- Object that contains information about card verification and security checks. title: securityCheck emvTag: type: object properties: hex: type: string description: Hex code of the EMV tag. value: type: string description: Value of the EMV tag. required: - hex - value description: Object that contains information about the EMV tag. title: emvTag CardBalanceBenefitCategory: type: string enum: - cash - foodStamp description: > Indicates if the balance relates to an EBT Cash account or EBT SNAP account. - `cash` – EBT Cash - `foodStamp` – EBT SNAP title: CardBalanceBenefitCategory cardBalance: type: object properties: benefitCategory: $ref: '#/components/schemas/CardBalanceBenefitCategory' description: > Indicates if the balance relates to an EBT Cash account or EBT SNAP account. - `cash` – EBT Cash - `foodStamp` – EBT SNAP amount: type: integer format: int64 description: >- Current balance of the account. This value is in the currency's lowest denomination, for example, cents. currency: $ref: '#/components/schemas/currency' required: - benefitCategory - amount - currency description: >- Object that contains information about the total funds available in the card. title: cardBalance card: type: object properties: type: type: string description: Card brand of the card, for example, Visa. entryMethod: $ref: '#/components/schemas/CardEntryMethod' description: Method that the device used to capture the card details. cardholderName: type: string description: Cardholder’s name. cardholderSignature: type: string description: Cardholder’s signature. cardNumber: type: string description: > Card number. In the response, our gateway shows only the first six digits and the last four digits of the card number, for example, 500165******0000. expiryDate: type: string description: Expiry date of the customer's card. The format is in **MMYY**. secureToken: $ref: '#/components/schemas/secureTokenSummary' securityChecks: $ref: '#/components/schemas/securityCheck' emvTags: type: array items: $ref: '#/components/schemas/emvTag' description: Array of emvTag objects. balances: type: array items: $ref: '#/components/schemas/cardBalance' description: >- Array of cardBalance objects. Our gateway returns this array only when the customer uses an Electronic Benefit Transfer (EBT) card. required: - type - entryMethod - cardNumber - expiryDate description: Object that contains the details of the payment card. title: card RefundSummaryStatus: type: string enum: - ready - pending - declined - complete - referral - pickup - reversal - returned - admin - expired - accepted description: Current status of the refund. title: RefundSummaryStatus RefundSummaryResponseCode: type: string enum: - A - D - E - P - R - C description: > Response from the processor. - `A` - The processor approved the transaction. - `D` - The processor declined the transaction. - `E` - The processor received the transaction but will process the transaction later. - `P` - The processor authorized a portion of the original amount of the transaction. - `R` - The issuer declined the transaction and indicated that the customer should contact their bank. - `C` - The issuer declined the transaction and indicated that the merchant should keep the card as it was reported lost or stolen. title: RefundSummaryResponseCode refundSummary: type: object properties: refundId: type: string description: Unique identifier of the refund. dateTime: type: string format: date-time description: Date and time that the refund was processed. currency: $ref: '#/components/schemas/currency' amount: type: integer format: int64 description: >- Amount of the refund. This value is in the currency’s lowest denomination, for example, cents. status: $ref: '#/components/schemas/RefundSummaryStatus' description: Current status of the refund. responseCode: $ref: '#/components/schemas/RefundSummaryResponseCode' description: > Response from the processor. - `A` - The processor approved the transaction. - `D` - The processor declined the transaction. - `E` - The processor received the transaction but will process the transaction later. - `P` - The processor authorized a portion of the original amount of the transaction. - `R` - The issuer declined the transaction and indicated that the customer should contact their bank. - `C` - The issuer declined the transaction and indicated that the merchant should keep the card as it was reported lost or stolen. responseMessage: type: string description: Description of the response from the processor. link: $ref: '#/components/schemas/link' required: - refundId - dateTime - currency - amount - status - responseCode - responseMessage description: Object that contains information about a refund. title: refundSummary SupportedOperationsItems: type: string enum: - capture - refund - fullyReverse - partiallyReverse - incrementAuthorization - adjustTip - addSignature - setAsReady - setAsPending title: SupportedOperationsItems supportedOperations: type: array items: $ref: '#/components/schemas/SupportedOperationsItems' description: | Array of operations that you can perform on the transaction. - `capture` - Capture the payment. - `refund` - Refund the payment. - `fullyReverse` - Fully reverse the transaction. - `partiallyReverse` - Partially reverse the payment. - `incrementAuthorization` - Increase the amount of the authorization. - `adjustTip` - Adjust the tip post-payment. - `addSignature` - Add a signature to the payment. - `setAsReady` - Set the transaction’s status to `ready`. - `setAsPending` - Set the transaction’s status to `pending`. title: supportedOperations TransactionResultType: type: string enum: - sale - refund - preAuthorization - preAuthorizationCompletion description: Transaction type. title: TransactionResultType TransactionResultEbtType: type: string enum: - cashPurchase - cashPurchaseWithCashback - foodStampPurchase - foodStampVoucherPurchase - foodStampReturn - foodStampVoucherReturn - cashBalanceInquiry - foodStampBalanceInquiry - cashWithdrawal description: Indicates the subtype of EBT in the transaction. title: TransactionResultEbtType TransactionResultStatus: type: string enum: - ready - pending - declined - complete - referral - pickup - reversal - admin - expired - accepted description: Current status of the transaction. title: TransactionResultStatus TransactionResultResponseCode: type: string enum: - A - D - E - P - R - C description: > Response from the processor. - `A` - The processor approved the transaction. - `D` - The processor declined the transaction. - `E` - The processor received the transaction but will process the transaction later. - `P` - The processor authorized a portion of the original amount of the transaction. - `R` - The issuer declined the transaction and indicated that the customer should contact their bank. - `C` - The issuer declined the transaction and indicated that the merchant should keep the card as it was reported lost or stolen. title: TransactionResultResponseCode transactionResult: type: object properties: type: $ref: '#/components/schemas/TransactionResultType' description: Transaction type. ebtType: $ref: '#/components/schemas/TransactionResultEbtType' description: Indicates the subtype of EBT in the transaction. status: $ref: '#/components/schemas/TransactionResultStatus' description: Current status of the transaction. approvalCode: type: string description: Authorization code that the processor assigned to the transaction. authorizedAmount: type: integer format: int64 description: > Amount that the processor authorized for the transaction. This value is in the currency’s lowest denomination, for example, cents. **Notes:** - For partial authorizations, this amount is lower than the amount in the request. - If the value for **authorizedAmount** is negative, this indicates that the merchant sent funds to the customer. currency: $ref: '#/components/schemas/currency' responseCode: $ref: '#/components/schemas/TransactionResultResponseCode' description: > Response from the processor. - `A` - The processor approved the transaction. - `D` - The processor declined the transaction. - `E` - The processor received the transaction but will process the transaction later. - `P` - The processor authorized a portion of the original amount of the transaction. - `R` - The issuer declined the transaction and indicated that the customer should contact their bank. - `C` - The issuer declined the transaction and indicated that the merchant should keep the card as it was reported lost or stolen. responseMessage: type: string description: Response description from the processor. processorResponseCode: type: string description: Original response code that the processor sent. cardSchemeReferenceId: type: string description: Identifier that the card brand assigns to the payment instruction. required: - status - responseCode description: Object that contains information about the transaction response details. title: transactionResult customField: type: object properties: name: type: string description: Name of the custom field. value: type: string description: Value for the custom field. required: - name - value title: customField payment: type: object properties: paymentId: type: string description: Unique identifier that our gateway assigned to the transaction. processingTerminalId: type: string description: Unique identifier of the terminal that initiated the transaction. operator: type: string description: Operator who initiated the request. order: $ref: '#/components/schemas/paymentOrder' customer: $ref: '#/components/schemas/retrievedCustomer' card: $ref: '#/components/schemas/card' refunds: type: array items: $ref: '#/components/schemas/refundSummary' description: > Array of refundSummary objects. Each object contains information about refunds linked to the transaction. supportedOperations: $ref: '#/components/schemas/supportedOperations' transactionResult: $ref: '#/components/schemas/transactionResult' customFields: type: array items: $ref: '#/components/schemas/customField' description: | Array of customField objects. required: - paymentId - processingTerminalId - order - card - transactionResult title: payment ErrorsItems: type: object properties: message: type: string description: Error message title: ErrorsItems ``` ### Example request ### Request POST [https://api.payroc.com/v1/payments/\{paymentId}/capture](https://api.payroc.com/v1/payments/\{paymentId}/capture) ```curl Payment curl -X POST https://api.payroc.com/v1/payments/M2MJOG6O2Y/capture \ -H "Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" ``` ```typescript Payment import { PayrocClient } from "payroc"; async function main() { const client = new PayrocClient(); await client.cardPayments.payments.capture("M2MJOG6O2Y", { idempotencyKey: "8e03978e-40d5-43e8-bc93-6894a57f9324", }); } main(); ``` ```python Payment from payroc import Payroc client = Payroc() client.card_payments.payments.capture( payment_id="M2MJOG6O2Y", idempotency_key="8e03978e-40d5-43e8-bc93-6894a57f9324", ) ``` ```java Payment package com.example.usage; import com.payroc.api.PayrocApiClient; import com.payroc.api.resources.cardpayments.payments.requests.PaymentCapture; public class Example { public static void main(String[] args) { PayrocApiClient client = PayrocApiClient .builder() .build(); client.cardPayments().payments().capture( "M2MJOG6O2Y", PaymentCapture .builder() .idempotencyKey("8e03978e-40d5-43e8-bc93-6894a57f9324") .build() ); } } ``` ```ruby Payment require "payroc" client = Payroc::Client.new client.card_payments.payments.capture( payment_id: "M2MJOG6O2Y", idempotency_key: "8e03978e-40d5-43e8-bc93-6894a57f9324" ) ``` ```csharp Payment using Payroc; using System.Threading.Tasks; using Payroc.CardPayments.Payments; namespace Usage; public class Example { public async Task Do() { var client = new PayrocClient(); await client.CardPayments.Payments.CaptureAsync( new PaymentCapture { PaymentId = "M2MJOG6O2Y", IdempotencyKey = "8e03978e-40d5-43e8-bc93-6894a57f9324" } ); } } ``` ```go Payment package main import ( "fmt" "net/http" "io" ) func main() { url := "https://api.payroc.com/v1/payments/M2MJOG6O2Y/capture" req, _ := http.NewRequest("POST", url, nil) req.Header.Add("Idempotency-Key", "8e03978e-40d5-43e8-bc93-6894a57f9324") req.Header.Add("Authorization", "Bearer ") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```php Payment request('POST', 'https://api.payroc.com/v1/payments/M2MJOG6O2Y/capture', [ 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', 'Idempotency-Key' => '8e03978e-40d5-43e8-bc93-6894a57f9324', ], ]); echo $response->getBody(); ``` ```swift Payment import Foundation let headers = [ "Idempotency-Key": "8e03978e-40d5-43e8-bc93-6894a57f9324", "Authorization": "Bearer ", "Content-Type": "application/json" ] let request = NSMutableURLRequest(url: NSURL(string: "https://api.payroc.com/v1/payments/M2MJOG6O2Y/capture")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ``` ### Response fields If your request is successful, we capture the pre-authorization and return a response. The response contains the following fields: ### Schema (`response.body`) ```yaml openapi: 3.1.0 info: title: API version: 1.0.0 paths: /payments/{paymentId}/capture: post: operationId: capture summary: Capture payment description: "Use this method to capture a pre-authorization. \n\nTo capture a pre-authorization, you need its paymentId. Our gateway returned the paymentId in the response of the [Create Payment](https://docs.payroc.com/api/schema/card-payments/payments/create) method.\n\n**Note:** If you don't have the paymentId, use our [List Payments](https://docs.payroc.com/api/schema/card-payments/payments/list) method to search for the payment.\n\nDepending on the amount you want to capture, complete the following:\n-\t**Capture the full amount of the pre-authorization** - Don't send a value for the amount parameter in your request.\n-\t**Capture less than the amount of the pre-authorization** - Send a value for the amount parameter in your request. \n-\t**Capture more than the amount of the pre-authorization** - Adjust the pre-authorization before you capture it. For more information about adjusting a pre-authorization, go to [Adjust Payment](https://docs.payroc.com/api/schema/card-payments/payments/adjust).\n\nIf your request is successful, our gateway takes the amount from the payment card. \n\n**Note:** For more information about pre-authorizations and captures, go to [Run a pre-authorization](https://docs.payroc.com/guides/integrate/run-a-pre-authorization).\n" tags: - subpackage_cardPayments.subpackage_cardPayments/payments parameters: - name: paymentId in: path description: >- Unique identifier of the payment that the merchant wants to retrieve. required: true schema: type: string - name: Idempotency-Key in: header description: >- Unique identifier that you generate for each request. You must use the [UUID v4 format](https://www.rfc-editor.org/rfc/rfc4122) for the identifier. For more information about the idempotency key, go to [Idempotency](https://docs.payroc.com/api/idempotency). required: true schema: type: string format: uuid responses: '200': description: Successful request. We captured the payment. content: application/json: schema: $ref: '#/components/schemas/payment' '400': description: Validation error content: application/json: schema: $ref: '#/components/schemas/400' '401': description: Identity could not be verified content: application/json: schema: $ref: '#/components/schemas/401' '403': description: Do not have permissions to perform this action content: application/json: schema: $ref: '#/components/schemas/403' '404': description: Resource not found content: application/json: schema: $ref: '#/components/schemas/404' '406': description: Not acceptable content: application/json: schema: $ref: '#/components/schemas/406' '409': description: Conflict content: application/json: schema: $ref: '#/components/schemas/409' '415': description: Unsupported media type content: application/json: schema: $ref: '#/components/schemas/415' '500': description: An error has occured content: application/json: schema: $ref: '#/components/schemas/500' requestBody: content: application/json: schema: $ref: '#/components/schemas/paymentCapture' servers: - url: https://api.payroc.com/v1 - url: https://api.uat.payroc.com/v1 components: schemas: '400': type: object properties: type: type: string description: URI reference identifying the problem type title: type: string description: Short description of the issue. status: type: integer description: Http status code detail: type: string description: Explanation of the problem errors: type: array items: $ref: '#/components/schemas/ErrorsItems' required: - type - title - status - detail title: '400' '401': type: object properties: type: type: string description: URI reference identifying the problem type title: type: string description: Short description of the issue. status: type: integer description: Http status code detail: type: string description: Explanation of the problem required: - type - title - status - detail title: '401' '403': type: object properties: type: type: string description: URI reference identifying the problem type title: type: string description: Short description of the issue. status: type: integer description: Http status code detail: type: string description: Explanation of the problem instance: type: string description: Resource path the action was attempted on resource: type: string description: Resource the action was attempted on required: - type - title - status - detail title: '403' '404': type: object properties: type: type: string description: URI reference identifying the problem type title: type: string description: Short description of the issue. status: type: integer description: Http status code detail: type: string description: Explanation of the problem resource: type: string description: Resource that was not found required: - type - title - status - detail title: '404' '406': type: object properties: type: type: string description: URI reference identifying the problem type title: type: string description: Short description of the issue. status: type: integer description: Http status code detail: type: string description: Explanation of the problem required: - type - title - status - detail title: '406' '409': type: object properties: type: type: string description: URI reference identifying the problem type title: type: string description: Short description of the issue. status: type: integer description: Http status code detail: type: string description: Explanation of the problem instance: type: string description: Resource path to the existing resource errors: type: array items: $ref: '#/components/schemas/ErrorsItems' link: $ref: '#/components/schemas/link' required: - type - title - status - detail title: '409' '415': type: object properties: type: type: string description: URI reference identifying the problem type title: type: string description: Short description of the issue. status: type: integer description: Http status code detail: type: string description: Explanation of the problem required: - type - title - status - detail title: '415' '500': type: object properties: type: type: string description: URI reference identifying the problem type title: type: string description: Short description of the issue. status: type: integer description: Http status code detail: type: string description: Explanation of the problem errors: type: array items: $ref: '#/components/schemas/ErrorsItems' required: - type - title - status - detail title: '500' TipType: type: string enum: - percentage - fixedAmount description: > Indicates if the tip is a fixed amount or a percentage. **Note:** Our gateway applies the percentage tip to the total amount of the transaction after tax. title: TipType TipMode: type: string enum: - prompted - adjusted description: > Indicates how the tip was added to the transaction. - `prompted` – The customer was prompted to add a tip during payment. - `adjusted` – The customer added a tip on the receipt for the merchant to adjust post-transaction. title: TipMode tip: type: object properties: type: $ref: '#/components/schemas/TipType' description: > Indicates if the tip is a fixed amount or a percentage. **Note:** Our gateway applies the percentage tip to the total amount of the transaction after tax. mode: $ref: '#/components/schemas/TipMode' description: > Indicates how the tip was added to the transaction. - `prompted` – The customer was prompted to add a tip during payment. - `adjusted` – The customer added a tip on the receipt for the merchant to adjust post-transaction. amount: type: integer format: int64 description: > If the value for type is `fixedAmount`, this value is the tip amount in the currency's lowest denomination, for example, cents. percentage: type: number format: double description: >- If the value for type is `percentage`, this value is the tip as a percentage. required: - type description: Object that contains information about the tip. title: tip surcharge: type: object properties: bypass: type: boolean description: > Indicates if the merchant wants to remove the surcharge fee from the transaction. - `true` - Gateway removes the surcharge fee from the transaction. - `false` - Gateway adds the fee to the transaction. amount: type: integer format: int64 description: > If the merchant added a surcharge fee, this value indicates the amount of the surcharge fee in the currency’s lowest denomination, for example, cents. percentage: type: number format: double description: >- If the merchant added a surcharge fee, this value indicates the surcharge percentage. description: | Object that contains information about the surcharge. title: surcharge choiceRate: type: object properties: applied: type: boolean default: false description: > Indicates if the merchant applies a choice rate to the transaction amount. Our gateway adds a choice rate to the transaction when the merchant offers an alternative payment type, but the customer chooses to pay by card. rate: type: number format: double description: > If the customer used a card to pay for the transaction, this value indicates the percentage that our gateway added to the transaction amount. **Note:** Our gateway returns a value for **rate** only if the value for **applied** in the request is `true`. amount: type: integer format: int64 description: > If the customer used a card to pay for the transaction, this value indicates the amount that our gateway added to the transaction amount. This value is in the currency’s lowest denomination, for example, cents. **Note:** Our gateway returns a value for **amount** only if the value for **applied** in the request is `true`. required: - applied - rate - amount description: > Object that contains information about the choice rate. We return this only if the value for offered was `true`. title: choiceRate DualPricingAlternativeTender: type: string enum: - card - cash - bankTransfer description: > Payment method that the merchant presented to the customer as an alternative to their chosen method. **Note:** For requests, if the value for **offered** is `true`, you must send a value for **alternativeTender** in the request. title: DualPricingAlternativeTender dualPricing: type: object properties: offered: type: boolean description: Indicates if the merchant offered dual pricing to the customer. choiceRate: $ref: '#/components/schemas/choiceRate' description: > Object that contains information about the choice rate. **Note:** For requests, if the value for **offered** is `true`, you must send this object in the request. alternativeTender: $ref: '#/components/schemas/DualPricingAlternativeTender' description: > Payment method that the merchant presented to the customer as an alternative to their chosen method. **Note:** For requests, if the value for **offered** is `true`, you must send a value for **alternativeTender** in the request. required: - offered description: Object that contains information about dual pricing. title: dualPricing tax: oneOf: - type: object properties: type: type: string enum: - amount description: 'Discriminator value: amount' amount: type: integer format: int64 description: >- Tax amount for the transaction. The value is in the currency's lowest denomination, for example, cents. name: type: string description: Name of the tax. required: - type - amount - name description: amount variant - type: object properties: type: type: string enum: - rate description: 'Discriminator value: rate' rate: type: number format: double description: Tax percentage for the transaction. name: type: string description: >- Name of the tax. A tax validation on the stored rate for the tax name is performed. required: - type - rate - name description: rate variant discriminator: propertyName: type description: "Polymorphic object that contains tax details. \n\nThe value of the type parameter determines which variant you should use: \n-\t`amount` - Tax is a fixed amount.\n-\t`rate` - Tax is a percentage.\n" title: tax convenienceFee: type: object properties: amount: type: integer format: int64 description: > If the merchant added a convenience fee, this value indicates the amount of the convenience fee in the currency’s lowest denomination, for example, cents. required: - amount description: >- Object that contains information about the convenience fee for the transaction. title: convenienceFee unitOfMeasure: type: string enum: - ACR - AMH - AMP - APZ - ARE - ASM - ASV - ATM - ATT - BAR - BFT - BHP - BHX - BIL - BLD - BLL - BQL - BTU - BUA - BUI - BX - CCT - CDL - CEL - CEN - CGM - CKG - CLF - CLT - CMK - CMT - CNP - CNT - COU - CS - CTM - CUR - CWA - DAA - DAD - DAY - DEC - DLT - DMK - DMQ - DMT - DPC - DPT - DRA - DRI - DRL - DRM - DTH - DTN - DWT - DZN - DZP - DZR - EA - EAC - FAH - FAR - FOT - FTK - FTQ - GBQ - GFI - GGR - GII - GLD - GLI - GLL - GRM - GRN - GRO - GRT - GWH - HAR - HBA - HGM - HIU - HLT - HMQ - HMT - HPA - HTZ - HUR - INH - INK - INQ - ITM - JOU - KBA - KEL - KGM - KGS - KHZ - KJO - KMH - KMK - KMQ - KMT - KNI - KNS - KNT - KPA - KPH - KPO - KPP - KSD - KSH - KTN - KUR - KVA - KVR - KVT - KWH - KWT - LBR - LBS - LEF - LPA - LTN - LTR - LUM - LUX - MAL - MAM - MAW - MBE - MBF - MBR - MCU - MGM - MHZ - MIK - MIL - MIN - MIO - MIU - MLD - MLT - MMK - MMQ - MMT - MON - MPA - MQH - MQS - MSK - MTK - MTQ - MTR - MTS - MVA - MWH - NAR - NBB - NCL - NEW - NIU - NMB - NMI - NMP - NMR - NPL - NPT - NRL - NTT - OHM - ONZ - OZA - OZI - PAL - PCB - PCE - PGL - PK - PSC - PTD - PTI - PTL - QAN - QTD - QTI - QTL - QTR - RPM - RPS - SAN - SCO - SCR - SEC - SET - SHT - SIE - SMI - SST - ST - STI - TAH - TNE - TPR - TQD - TRL - TSD - TSH - VLT - WCD - WEB - WEE - WHR - WSD - WTT - YDK - YDQ description: >- Unit of measurement for the item. For more information about units of measurement, go to [Units of measurement](https://docs.payroc.com/knowledge/basic-concepts/units-of-measurement). title: unitOfMeasure lineItemRequest: type: object properties: commodityCode: type: string description: Commodity code of the item. productCode: type: string description: Product code of the item. description: type: string description: Description of the item. unitOfMeasure: $ref: '#/components/schemas/unitOfMeasure' unitPrice: type: integer format: int64 description: Price of each unit. quantity: type: number format: double description: Number of units. discountRate: type: number format: double description: Discount rate that the merchant applies to the item. taxes: type: array items: $ref: '#/components/schemas/tax' description: >- Array of objects that contain information about each tax that applies to the item. required: - unitPrice - quantity description: List of line items. title: lineItemRequest itemizedBreakdownRequest: type: object properties: subtotal: type: integer format: int64 description: >- Amount of the transaction before tax and fees. The value is in the currency’s lowest denomination, for example, cents. cashbackAmount: type: integer format: int64 description: Amount of cashback for the transaction. tip: $ref: '#/components/schemas/tip' description: Object that contains tip information for the transaction. surcharge: $ref: '#/components/schemas/surcharge' description: Object that contains surcharge information for the transaction. dualPricing: $ref: '#/components/schemas/dualPricing' description: Object that contains dual pricing information for the transaction. taxes: type: array items: $ref: '#/components/schemas/tax' description: "Array of polymorphic tax objects, which contain information about a tax. \n\nThe value of the type parameter determines which variant you should use: \n-\t`amount` - Tax is a fixed amount.\n-\t`rate` - Tax is a percentage.\n" dutyAmount: type: integer format: int64 description: > Amount of duties or fees that apply to the order. The value is in the currency's lowest denomination, for example, cents. freightAmount: type: integer format: int64 description: > Amount for shipping in the currency's lowest denomination, for example, cents. convenienceFee: $ref: '#/components/schemas/convenienceFee' items: type: array items: $ref: '#/components/schemas/lineItemRequest' description: >- Array of objects that contain information about each item that the customer purchased. required: - subtotal description: Object that contains information about the breakdown of the transaction. title: itemizedBreakdownRequest paymentCapture: type: object properties: processingTerminalId: type: string description: Unique identifier that our gateway assigned to the terminal. operator: type: string description: Operator who captured the payment. amount: type: integer format: int64 description: > Amount that the merchant wants to capture. The value is in the currency's lowest denomination, for example, cents. **Note:** If the merchant does not send an amount, we capture the total amount of the transaction. breakdown: $ref: '#/components/schemas/itemizedBreakdownRequest' description: >- Object that contains the details of the payment that the merchant wants to capture. title: paymentCapture currency: type: string enum: - AED - AFN - ALL - AMD - ANG - AOA - ARS - AUD - AWG - AZN - BAM - BBD - BDT - BGN - BHD - BIF - BMD - BND - BOB - BOV - BRL - BSD - BTN - BWP - BYR - BZD - CAD - CDF - CHE - CHF - CHW - CLF - CLP - CNY - COP - COU - CRC - CUC - CUP - CVE - CZK - DJF - DKK - DOP - DZD - EGP - ERN - ETB - EUR - FJD - FKP - GBP - GEL - GHS - GIP - GMD - GNF - GTQ - GYD - HKD - HNL - HRK - HTG - HUF - IDR - ILS - INR - IQD - IRR - ISK - JMD - JOD - JPY - KES - KGS - KHR - KMF - KPW - KRW - KWD - KYD - KZT - LAK - LBP - LKR - LRD - LSL - LTL - LVL - LYD - MAD - MDL - MGA - MKD - MMK - MNT - MOP - MRO - MRU - MUR - MVR - MWK - MXN - MXV - MYR - MZN - NAD - NGN - NIO - NOK - NPR - NZD - OMR - PAB - PEN - PGK - PHP - PKR - PLN - PYG - QAR - RON - RSD - RUB - RWF - SAR - SBD - SCR - SDG - SEK - SGD - SHP - SLL - SOS - SRD - SSP - STD - STN - SVC - SYP - SZL - THB - TJS - TMT - TND - TOP - TRY - TTD - TWD - TZS - UAH - UGX - USD - USN - USS - UYI - UYU - UZS - VEF - VES - VND - VUV - WST - XAF - XCD - XOF - XPF - YER - ZAR - ZMW - ZWL description: >- Currency of the transaction. The value for the currency follows the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard. title: currency dccOffer: type: object properties: accepted: type: boolean description: Indicates if the cardholder accepted DCC offer. offerReference: type: string description: Unique identifier of the DCC offer. fxAmount: type: integer format: int64 description: >- Amount in the cardholder’s currency in the currency’s lowest denomination, for example, cents. fxCurrency: $ref: '#/components/schemas/currency' description: >- Currency of the transaction in the card’s currency. The value for the currency follows the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard. fxCurrencyCode: type: string description: >- Three-digit currency code for the card. This code follows the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard. fxCurrencyExponent: type: integer description: > Number of decimal places between the smallest currency unit and a whole currency unit. For example, for GBP, the smallest currency unit is 1p and it is equal to £0.01. If you use GBP, the value for **fxCurrencyExponent** is 2. fxRate: type: number format: double description: Foreign exchange rate for the card's currency. markup: type: number format: double description: >- Markup percentage rate that the DCC provider applies to the foreign exchange rate. markupText: type: string description: Supporting text for the markup rate. provider: type: string description: Name of the DCC provider. source: type: string description: Source that the DCC provider used to get the foreign exchange rates. required: - fxAmount - fxCurrency - fxRate - markup description: > Object that contains information about the dynamic currency conversion (DCC) offer. For more information about DCC, go to [Dynamic Currency Conversion](https://docs.payroc.com/knowledge/card-payments/dynamic-currency-conversion). title: dccOffer StandingInstructionsSequence: type: string enum: - first - subsequent description: Position of the transaction in the payment plan sequence. title: StandingInstructionsSequence StandingInstructionsProcessingModel: type: string enum: - unscheduled - recurring - installment description: > Indicates the type of payment instruction. - 'unscheduled' – The payment is not part of a regular billing cycle. - 'recurring' – The payment is part of a regular billing cycle with no end date. - 'installment' – The payment is part of a regular billing cycle with an end date. title: StandingInstructionsProcessingModel firstTxnReferenceData: type: object properties: paymentId: type: string description: > Unique identifier of the first payment. **Note:** We recommend that you always send a value for **paymentId**. cardSchemeReferenceId: type: string description: Identifier that the card brand assigns to the payment instruction. description: >- Object that contains information about the initial payment for the payment instruction. title: firstTxnReferenceData standingInstructions: type: object properties: sequence: $ref: '#/components/schemas/StandingInstructionsSequence' description: Position of the transaction in the payment plan sequence. processingModel: $ref: '#/components/schemas/StandingInstructionsProcessingModel' description: > Indicates the type of payment instruction. - 'unscheduled' – The payment is not part of a regular billing cycle. - 'recurring' – The payment is part of a regular billing cycle with no end date. - 'installment' – The payment is part of a regular billing cycle with an end date. referenceDataOfFirstTxn: $ref: '#/components/schemas/firstTxnReferenceData' description: >- Object that contains information about the initial payment for the payment instruction. required: - sequence - processingModel description: >- If you don't use our Subscriptions mechanism, include this section to configure your standing/recurring orders. title: standingInstructions retrievedTax: type: object properties: name: type: string description: Name of the tax. rate: type: number format: double description: Tax percentage for the transaction. amount: type: integer format: int64 description: >- Amount of tax that was applied to the transaction. The value is in the currency's lowest denomination, for example, cents. required: - name - rate title: retrievedTax lineItem: type: object properties: commodityCode: type: string description: Commodity code of the item. productCode: type: string description: Product code of the item. description: type: string description: Description of the item. unitOfMeasure: $ref: '#/components/schemas/unitOfMeasure' unitPrice: type: integer format: int64 description: Price of each unit. quantity: type: number format: double description: Number of units. discountRate: type: number format: double description: Discount rate that the merchant applies to the item. taxes: type: array items: $ref: '#/components/schemas/retrievedTax' description: >- Array of objects that contain information about each tax that applies to the item. required: - unitPrice - quantity description: List of line items. title: lineItem itemizedBreakdown: type: object properties: subtotal: type: integer format: int64 description: >- Amount of the transaction before tax and fees. The value is in the currency’s lowest denomination, for example, cents. cashbackAmount: type: integer format: int64 description: Amount of cashback for the transaction. tip: $ref: '#/components/schemas/tip' description: Object that contains tip information for the transaction. surcharge: $ref: '#/components/schemas/surcharge' description: Object that contains surcharge information for the transaction. dualPricing: $ref: '#/components/schemas/dualPricing' description: Object that contains dual pricing information for the transaction. taxes: type: array items: $ref: '#/components/schemas/retrievedTax' description: List of taxes. dutyAmount: type: integer format: int64 description: > Amount of duties or fees that apply to the order. The value is in the currency's lowest denomination, for example, cents. freightAmount: type: integer format: int64 description: > Amount for shipping in the currency's lowest denomination, for example, cents. convenienceFee: $ref: '#/components/schemas/convenienceFee' items: type: array items: $ref: '#/components/schemas/lineItem' description: >- Array of objects that contain information about each item that the customer purchased. required: - subtotal description: Object that contains information about the breakdown of the transaction. title: itemizedBreakdown paymentOrder: type: object properties: orderId: type: string description: A unique identifier assigned by the merchant. dateTime: type: string format: date-time description: >- Date and time that the processor processed the transaction. Our gateway returns this value in the ISO 8601 format. description: type: string description: Description of the transaction. amount: type: integer format: int64 description: >- Total amount of the transaction. The value is in the currency’s lowest denomination, for example, cents. currency: $ref: '#/components/schemas/currency' dccOffer: $ref: '#/components/schemas/dccOffer' standingInstructions: $ref: '#/components/schemas/standingInstructions' breakdown: $ref: '#/components/schemas/itemizedBreakdown' required: - orderId - amount - currency description: Object that contains information about the payment. title: paymentOrder retrievedAddress: type: object properties: address1: type: string description: Address line 1. address2: type: string description: Address line 2. address3: type: string description: Address line 3. city: type: string description: City. state: type: string description: Name of the state or state abbreviation. country: type: string description: >- Two-digit country code for the country that the business operates in. The format follows the [ISO-3166-1](https://www.iso.org/iso-3166-country-codes.html) standard. postalCode: type: string description: Zip code or postal code. description: Object that contains information about the address. title: retrievedAddress retrievedShipping: type: object properties: recipientName: type: string description: Recipient's name. address: $ref: '#/components/schemas/retrievedAddress' description: >- Object that contains information about the customer and their shipping address. title: retrievedShipping contactMethod: oneOf: - type: object properties: type: type: string enum: - email description: 'Discriminator value: email' value: type: string description: Email address. required: - type - value description: email variant - type: object properties: type: type: string enum: - phone description: 'Discriminator value: phone' value: type: string description: Phone number. required: - type - value description: phone variant - type: object properties: type: type: string enum: - mobile description: 'Discriminator value: mobile' value: type: string description: Mobile number. required: - type - value description: mobile variant - type: object properties: type: type: string enum: - fax description: 'Discriminator value: fax' value: type: string description: Fax number. required: - type - value description: fax variant discriminator: propertyName: type title: contactMethod RetrievedCustomerNotificationLanguage: type: string enum: - en - fr description: > Language that the customer uses for notifications. This code follows the [ISO 639-1](https://www.iso.org/iso-639-language-code) alpha-2 standard. title: RetrievedCustomerNotificationLanguage retrievedCustomer: type: object properties: firstName: type: string description: Customer's first name. lastName: type: string description: Customer's last name. dateOfBirth: type: string format: date description: >- Customer's date of birth. The format for this value is **YYYY-MM-DD**. referenceNumber: type: string description: > Identifier of the transaction, also known as a customer code. For requests, you must send a value for **referenceNumber** if the customer provides one. billingAddress: $ref: '#/components/schemas/retrievedAddress' description: >- Object that contains information about the address that the card is registered to. shippingAddress: $ref: '#/components/schemas/retrievedShipping' contactMethods: type: array items: $ref: '#/components/schemas/contactMethod' description: "Array of polymorphic objects, which contain contact information. \n\nThe value of the type parameter determines which variant you should use: \n-\t`email` - Email address \n-\t`phone` - Phone number\n-\t`mobile` - Mobile number\n-\t`fax` - Fax number\n" notificationLanguage: $ref: '#/components/schemas/RetrievedCustomerNotificationLanguage' description: > Language that the customer uses for notifications. This code follows the [ISO 639-1](https://www.iso.org/iso-639-language-code) alpha-2 standard. description: >- Object that contains the customer's contact details and address information. title: retrievedCustomer CardEntryMethod: type: string enum: - icc - keyed - swiped - swipedFallback - contactlessIcc - contactlessMsr description: Method that the device used to capture the card details. title: CardEntryMethod SecureTokenSummaryStatus: type: string enum: - notValidated - cvvValidated - validationFailed - issueNumberValidated - cardNumberValidated - bankAccountValidated description: > Status of the customer's bank account. The processor performs a security check on the customer's bank account and returns the status of the account. **Note:** Depending on the merchant's account settings, this feature may be unavailable. title: SecureTokenSummaryStatus link: type: object properties: rel: type: string description: >- Indicates the relationship between the current resource and the target resource. method: type: string description: HTTP method that you need to use with the target resource. href: type: string description: URL of the target resource. required: - rel - method - href description: Object that contains HATEOAS links for the resource. title: link secureTokenSummary: type: object properties: secureTokenId: type: string description: Unique identifier that the merchant assigned to the secure token. customerName: type: string description: Customer's name. token: type: string description: > Token that the merchant can use in future transactions to represent the customer's payment details. The token: - Begins with the six-digit identification number **296753**. - Contains up to 12 digits. - Contains a single check digit that we calculate using the Luhn algorithm. status: $ref: '#/components/schemas/SecureTokenSummaryStatus' description: > Status of the customer's bank account. The processor performs a security check on the customer's bank account and returns the status of the account. **Note:** Depending on the merchant's account settings, this feature may be unavailable. link: $ref: '#/components/schemas/link' required: - secureTokenId - customerName - token - status description: Object that contains information about the secure token. title: secureTokenSummary SecurityCheckCvvResult: type: string enum: - M - 'N' - P - U description: > Indicates if the card verification value (CVV) that the customer provided in the request matches the CVV on the card. - `M` – The CVV matches the card’s CVV. - `N` – The CVV doesn’t match the card’s CVV. - `P` – The CVV wasn’t processed. - `U` – The CVV isn’t registered. **Note:** Our gateway doesn’t automatically decline transactions when the CVV doesn’t match the card’s CVV, unless the merchant selects this setting in their account. title: SecurityCheckCvvResult SecurityCheckAvsResult: type: string enum: - 'Y' - A - Z - 'N' - U - R - G - S - F - W - X description: > Indicates if the address that the customer provided in the request matches the address linked to the card. - `Y` – The address in the request matches the address linked to the card. - `N` – The address in the request doesn’t match the address linked to the card. - `A` – The street address matches, but ZIP code or postal code doesn’t match. - `Z` - The ZIP code or postal code matches, but street address doesn’t match. - `U` – The address information is unavailable. - `G` – The issuer or card brand doesn’t support the Address Verification Service (AVS). - `R` – The AVS is currently unavailable. Try again later. - `S` – There was no AVS data in the request, or it was sent in the wrong format. - `F` - For UK addresses, the address in the request matches the address linked to the card. - `W` – For US addresses, the nine-digit ZIP code or postal code in the request matches the address linked to the card but the street address doesn’t. - `X` – For US addresses, the nine-digit ZIP code or postal code and the street address matches the address linked to the card. **Note:** Our gateway doesn’t automatically decline transactions when the address doesn’t match the address linked to the card, unless the merchant selects this setting in their account. title: SecurityCheckAvsResult securityCheck: type: object properties: cvvResult: $ref: '#/components/schemas/SecurityCheckCvvResult' description: > Indicates if the card verification value (CVV) that the customer provided in the request matches the CVV on the card. - `M` – The CVV matches the card’s CVV. - `N` – The CVV doesn’t match the card’s CVV. - `P` – The CVV wasn’t processed. - `U` – The CVV isn’t registered. **Note:** Our gateway doesn’t automatically decline transactions when the CVV doesn’t match the card’s CVV, unless the merchant selects this setting in their account. avsResult: $ref: '#/components/schemas/SecurityCheckAvsResult' description: > Indicates if the address that the customer provided in the request matches the address linked to the card. - `Y` – The address in the request matches the address linked to the card. - `N` – The address in the request doesn’t match the address linked to the card. - `A` – The street address matches, but ZIP code or postal code doesn’t match. - `Z` - The ZIP code or postal code matches, but street address doesn’t match. - `U` – The address information is unavailable. - `G` – The issuer or card brand doesn’t support the Address Verification Service (AVS). - `R` – The AVS is currently unavailable. Try again later. - `S` – There was no AVS data in the request, or it was sent in the wrong format. - `F` - For UK addresses, the address in the request matches the address linked to the card. - `W` – For US addresses, the nine-digit ZIP code or postal code in the request matches the address linked to the card but the street address doesn’t. - `X` – For US addresses, the nine-digit ZIP code or postal code and the street address matches the address linked to the card. **Note:** Our gateway doesn’t automatically decline transactions when the address doesn’t match the address linked to the card, unless the merchant selects this setting in their account. description: >- Object that contains information about card verification and security checks. title: securityCheck emvTag: type: object properties: hex: type: string description: Hex code of the EMV tag. value: type: string description: Value of the EMV tag. required: - hex - value description: Object that contains information about the EMV tag. title: emvTag CardBalanceBenefitCategory: type: string enum: - cash - foodStamp description: > Indicates if the balance relates to an EBT Cash account or EBT SNAP account. - `cash` – EBT Cash - `foodStamp` – EBT SNAP title: CardBalanceBenefitCategory cardBalance: type: object properties: benefitCategory: $ref: '#/components/schemas/CardBalanceBenefitCategory' description: > Indicates if the balance relates to an EBT Cash account or EBT SNAP account. - `cash` – EBT Cash - `foodStamp` – EBT SNAP amount: type: integer format: int64 description: >- Current balance of the account. This value is in the currency's lowest denomination, for example, cents. currency: $ref: '#/components/schemas/currency' required: - benefitCategory - amount - currency description: >- Object that contains information about the total funds available in the card. title: cardBalance card: type: object properties: type: type: string description: Card brand of the card, for example, Visa. entryMethod: $ref: '#/components/schemas/CardEntryMethod' description: Method that the device used to capture the card details. cardholderName: type: string description: Cardholder’s name. cardholderSignature: type: string description: Cardholder’s signature. cardNumber: type: string description: > Card number. In the response, our gateway shows only the first six digits and the last four digits of the card number, for example, 500165******0000. expiryDate: type: string description: Expiry date of the customer's card. The format is in **MMYY**. secureToken: $ref: '#/components/schemas/secureTokenSummary' securityChecks: $ref: '#/components/schemas/securityCheck' emvTags: type: array items: $ref: '#/components/schemas/emvTag' description: Array of emvTag objects. balances: type: array items: $ref: '#/components/schemas/cardBalance' description: >- Array of cardBalance objects. Our gateway returns this array only when the customer uses an Electronic Benefit Transfer (EBT) card. required: - type - entryMethod - cardNumber - expiryDate description: Object that contains the details of the payment card. title: card RefundSummaryStatus: type: string enum: - ready - pending - declined - complete - referral - pickup - reversal - returned - admin - expired - accepted description: Current status of the refund. title: RefundSummaryStatus RefundSummaryResponseCode: type: string enum: - A - D - E - P - R - C description: > Response from the processor. - `A` - The processor approved the transaction. - `D` - The processor declined the transaction. - `E` - The processor received the transaction but will process the transaction later. - `P` - The processor authorized a portion of the original amount of the transaction. - `R` - The issuer declined the transaction and indicated that the customer should contact their bank. - `C` - The issuer declined the transaction and indicated that the merchant should keep the card as it was reported lost or stolen. title: RefundSummaryResponseCode refundSummary: type: object properties: refundId: type: string description: Unique identifier of the refund. dateTime: type: string format: date-time description: Date and time that the refund was processed. currency: $ref: '#/components/schemas/currency' amount: type: integer format: int64 description: >- Amount of the refund. This value is in the currency’s lowest denomination, for example, cents. status: $ref: '#/components/schemas/RefundSummaryStatus' description: Current status of the refund. responseCode: $ref: '#/components/schemas/RefundSummaryResponseCode' description: > Response from the processor. - `A` - The processor approved the transaction. - `D` - The processor declined the transaction. - `E` - The processor received the transaction but will process the transaction later. - `P` - The processor authorized a portion of the original amount of the transaction. - `R` - The issuer declined the transaction and indicated that the customer should contact their bank. - `C` - The issuer declined the transaction and indicated that the merchant should keep the card as it was reported lost or stolen. responseMessage: type: string description: Description of the response from the processor. link: $ref: '#/components/schemas/link' required: - refundId - dateTime - currency - amount - status - responseCode - responseMessage description: Object that contains information about a refund. title: refundSummary SupportedOperationsItems: type: string enum: - capture - refund - fullyReverse - partiallyReverse - incrementAuthorization - adjustTip - addSignature - setAsReady - setAsPending title: SupportedOperationsItems supportedOperations: type: array items: $ref: '#/components/schemas/SupportedOperationsItems' description: | Array of operations that you can perform on the transaction. - `capture` - Capture the payment. - `refund` - Refund the payment. - `fullyReverse` - Fully reverse the transaction. - `partiallyReverse` - Partially reverse the payment. - `incrementAuthorization` - Increase the amount of the authorization. - `adjustTip` - Adjust the tip post-payment. - `addSignature` - Add a signature to the payment. - `setAsReady` - Set the transaction’s status to `ready`. - `setAsPending` - Set the transaction’s status to `pending`. title: supportedOperations TransactionResultType: type: string enum: - sale - refund - preAuthorization - preAuthorizationCompletion description: Transaction type. title: TransactionResultType TransactionResultEbtType: type: string enum: - cashPurchase - cashPurchaseWithCashback - foodStampPurchase - foodStampVoucherPurchase - foodStampReturn - foodStampVoucherReturn - cashBalanceInquiry - foodStampBalanceInquiry - cashWithdrawal description: Indicates the subtype of EBT in the transaction. title: TransactionResultEbtType TransactionResultStatus: type: string enum: - ready - pending - declined - complete - referral - pickup - reversal - admin - expired - accepted description: Current status of the transaction. title: TransactionResultStatus TransactionResultResponseCode: type: string enum: - A - D - E - P - R - C description: > Response from the processor. - `A` - The processor approved the transaction. - `D` - The processor declined the transaction. - `E` - The processor received the transaction but will process the transaction later. - `P` - The processor authorized a portion of the original amount of the transaction. - `R` - The issuer declined the transaction and indicated that the customer should contact their bank. - `C` - The issuer declined the transaction and indicated that the merchant should keep the card as it was reported lost or stolen. title: TransactionResultResponseCode transactionResult: type: object properties: type: $ref: '#/components/schemas/TransactionResultType' description: Transaction type. ebtType: $ref: '#/components/schemas/TransactionResultEbtType' description: Indicates the subtype of EBT in the transaction. status: $ref: '#/components/schemas/TransactionResultStatus' description: Current status of the transaction. approvalCode: type: string description: Authorization code that the processor assigned to the transaction. authorizedAmount: type: integer format: int64 description: > Amount that the processor authorized for the transaction. This value is in the currency’s lowest denomination, for example, cents. **Notes:** - For partial authorizations, this amount is lower than the amount in the request. - If the value for **authorizedAmount** is negative, this indicates that the merchant sent funds to the customer. currency: $ref: '#/components/schemas/currency' responseCode: $ref: '#/components/schemas/TransactionResultResponseCode' description: > Response from the processor. - `A` - The processor approved the transaction. - `D` - The processor declined the transaction. - `E` - The processor received the transaction but will process the transaction later. - `P` - The processor authorized a portion of the original amount of the transaction. - `R` - The issuer declined the transaction and indicated that the customer should contact their bank. - `C` - The issuer declined the transaction and indicated that the merchant should keep the card as it was reported lost or stolen. responseMessage: type: string description: Response description from the processor. processorResponseCode: type: string description: Original response code that the processor sent. cardSchemeReferenceId: type: string description: Identifier that the card brand assigns to the payment instruction. required: - status - responseCode description: Object that contains information about the transaction response details. title: transactionResult customField: type: object properties: name: type: string description: Name of the custom field. value: type: string description: Value for the custom field. required: - name - value title: customField payment: type: object properties: paymentId: type: string description: Unique identifier that our gateway assigned to the transaction. processingTerminalId: type: string description: Unique identifier of the terminal that initiated the transaction. operator: type: string description: Operator who initiated the request. order: $ref: '#/components/schemas/paymentOrder' customer: $ref: '#/components/schemas/retrievedCustomer' card: $ref: '#/components/schemas/card' refunds: type: array items: $ref: '#/components/schemas/refundSummary' description: > Array of refundSummary objects. Each object contains information about refunds linked to the transaction. supportedOperations: $ref: '#/components/schemas/supportedOperations' transactionResult: $ref: '#/components/schemas/transactionResult' customFields: type: array items: $ref: '#/components/schemas/customField' description: | Array of customField objects. required: - paymentId - processingTerminalId - order - card - transactionResult title: payment ErrorsItems: type: object properties: message: type: string description: Error message title: ErrorsItems ``` ### Example response ### Response (200) ```json { "paymentId": "M2MJOG6O2Y", "processingTerminalId": "1234001", "order": { "orderId": "OrderRef6543", "amount": 4999, "currency": "USD", "dateTime": "2024-07-02T15:30:00Z", "description": "Large Pepperoni Pizza" }, "card": { "type": "MasterCard", "entryMethod": "keyed", "cardNumber": "453985******7062", "expiryDate": "1230", "securityChecks": { "cvvResult": "M", "avsResult": "Y" } }, "transactionResult": { "status": "ready", "responseCode": "A", "type": "sale", "approvalCode": "OK3", "authorizedAmount": 4999, "currency": "USD", "responseMessage": "OK3" }, "operator": "Jane", "customer": { "firstName": "Sarah", "lastName": "Hopper", "billingAddress": { "address1": "1 Example Ave.", "address2": "Example Address Line 2", "address3": "Example Address Line 3", "city": "Chicago", "state": "Illinois", "country": "US", "postalCode": "60056" }, "shippingAddress": { "recipientName": "Sarah Hopper", "address": { "address1": "1 Example Ave.", "address2": "Example Address Line 2", "address3": "Example Address Line 3", "city": "Chicago", "state": "Illinois", "country": "US", "postalCode": "60056" } } }, "supportedOperations": [ "capture", "fullyReverse", "partiallyReverse", "incrementAuthorization", "adjustTip", "setAsPending" ], "customFields": [ { "name": "yourCustomField", "value": "abc123" } ] } ```