> 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 AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.payroc.com/_mcp/server. # Run a sale > Run a card sale on a Payroc Cloud device by submitting a payment instruction via POST to the Devices endpoint, polling for status, and retrieving the final payment result. An AI skill is available for this guide, get it on the [Skills Marketplace (GitHub)](https://github.com/payroc/skills). After you configure a device for Payroc Cloud, program your POS to send a payment instruction to the payment device. Your POS then checks the status of the instruction until the payment finishes, and views the details of the payment. ## How it works ```mermaid sequenceDiagram participant POS as Your POS participant GW as Gateway participant D as Payment device rect rgba(0, 81, 194, 0.4) Note over POS,D: 1. Submit a payment instruction POS->>GW: POST /devices/{serialNumber}/payment-instructions GW->>D: Send the payment instruction GW-->>POS: paymentInstructionId, status = inProgress end rect rgba(0, 224, 184, 0.3) Note over POS,D: 2. Check the status of the payment instruction Note over D: Cardholder taps their card and
completes the payment on the device loop Until the status changes from inProgress POS->>GW: GET /payment-instructions/{paymentInstructionId} Note over GW: Waits up to a minute
for the status to change GW-->>POS: Current status
(when complete, includes a link to the payment) end end rect rgba(0, 224, 184, 0.3) Note over POS,GW: 3. View the details of the payment POS->>GW: GET /payments/{paymentId} GW-->>POS: Payment details (approved or declined) end opt Cancel while the status is inProgress POS->>GW: DELETE /payment-instructions/{paymentInstructionId} GW-->>POS: Payment instruction cancelled end ``` 1. Your POS submits a payment instruction to the device. Our gateway sends the instruction to the device and returns a `paymentInstructionId` with a status of `inProgress`. 2. The cardholder completes the payment on the device. Your POS checks the status of the payment instruction. Our gateway waits up to a minute for the status to change before it responds. If the status is still `inProgress`, your POS sends another request and keeps checking until the status changes. 3. When the payment finishes, your POS uses the link in the response to view the details of the payment and to check whether the processor approved it or declined it. You can also cancel the payment instruction while its status is `inProgress`. ### Before you begin [Authenticate your requests](/api/authentication) before making API calls. If your request fails, see [Errors](/api/errors). ## Step 1. Submit a payment instruction To submit a payment instruction to the device, send a POST request to the Devices endpoint. | Environment | URL | | :---------- | :-------------------------------------------------------------------------- | | Test | `https://api.uat.payroc.com/v1/devices/{serialNumber}/payment-instructions` | | Production | `https://api.payroc.com/v1/devices/{serialNumber}/payment-instructions` | ### Request parameters To create the body of your request, use the following parameters:\ \ Use this method to submit an instruction request to initiate a sale on a payment device. In the request, include the order amount and currency. When you send a successful request, our gateway returns information about the payment instruction and a paymentInstructionId, which you need for the following methods: - [Retrieve payment instruction](https://docs.payroc.com/api/schema/payroc-cloud/payment-instructions/retrieve) - View the details of the payment instruction. - [Cancel payment instruction](https://docs.payroc.com/api/schema/payroc-cloud/payment-instructions/delete) - Cancel the payment instruction. tags: - subpackage_payrocCloud/paymentInstructions parameters: - name: serialNumber in: path description: Serial number of the merchant’s payment device. required: true schema: type: string minLength: 1 maxLength: 64 - 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: '202': description: Successful request. We accepted the payment instruction. content: application/json: schema: $ref: '#/components/schemas/paymentInstruction' '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/paymentInstructionRequest' servers: - url: https://api.payroc.com/v1 description: Production - url: https://api.uat.payroc.com/v1 description: UAT 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' 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 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 exclusiveMinimum: 0 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 maximum: 100 exclusiveMinimum: 0 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 exclusiveMinimum: 0 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 maximum: 100 exclusiveMinimum: 0 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 maximum: 100 exclusiveMinimum: 0 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 exclusiveMinimum: 0 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 HealthcareExpenseType: type: string enum: - copay - clinic - dental - prescription - transit - vision description: Type of healthcare expense. title: HealthcareExpenseType healthcareExpense: type: object properties: type: $ref: '#/components/schemas/HealthcareExpenseType' description: Type of healthcare expense. amount: type: integer format: int64 exclusiveMinimum: 0 description: >- Amount of the healthcare expense. The value is in the currency's lowest denomination, for example, cents. required: - type - amount description: Object that contains information about a healthcare expense. title: healthcareExpense taxRate: type: object properties: rate: type: number format: double minimum: 0 maximum: 99.99999 description: > Tax percentage for the transaction. Required for [Level 3 and CEDP transactions](https://docs.payroc.com/knowledge/card-payments/enhanced-data). name: type: string minLength: 1 maxLength: 64 description: >- Name of the tax. A tax validation on the stored rate for the tax name is performed. required: - rate - name title: taxRate breakdownForPaymentInstructions: 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. Required for [Level 2, Level 3, and CEDP transactions](https://docs.payroc.com/knowledge/card-payments/enhanced-data). 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. healthcareExpenses: type: array items: $ref: '#/components/schemas/healthcareExpense' description: >- Array of healthcareExpense objects that contain information about healthcare expenses. taxes: type: array items: $ref: '#/components/schemas/taxRate' description: List of taxes. required: - subtotal description: Object that contains information about the breakdown of the transaction. title: breakdownForPaymentInstructions paymentInstructionOrder: type: object properties: orderId: type: string minLength: 1 maxLength: 24 description: Unique identifier that the merchant assigns to the transaction. 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](https://www.iso.org/iso-8601-date-and-time-format.html) format. description: type: string minLength: 0 maxLength: 1024 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' acceptPartialAmount: type: boolean default: false description: > Indicates if the merchant accepts a partial authorization for this transaction. - `true` — If the issuer cannot approve the full amount, the gateway accepts a partial authorization and returns the approved amount. The integrator is responsible for collecting the remaining balance via a follow-up payment. - `false` — Standard authorization behavior. If the issuer cannot approve the full amount, the transaction is declined. **Note:** When this field is omitted, the default is `false` and standard authorization behavior applies. breakdown: $ref: '#/components/schemas/breakdownForPaymentInstructions' required: - orderId - amount - currency description: Object that contains information about the payment. title: paymentInstructionOrder address: type: object properties: address1: type: string maxLength: 150 description: Address line 1. address2: type: string maxLength: 150 description: Address line 2. address3: type: string maxLength: 150 description: Address line 3. city: type: string maxLength: 50 description: City. state: type: string maxLength: 50 description: Name of the state or state abbreviation. country: type: string minLength: 2 maxLength: 2 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 maxLength: 10 description: Zip code or postal code. required: - address1 - city - state - country - postalCode description: Object that contains information about the address. title: address shipping: type: object properties: recipientName: type: string minLength: 0 maxLength: 50 description: > Recipient's name. Required for [Level 3 and CEDP transactions](https://docs.payroc.com/knowledge/card-payments/enhanced-data). address: $ref: '#/components/schemas/address' description: > Object that contains information about the shipping address. Required for [Level 3 and CEDP transactions](https://docs.payroc.com/knowledge/card-payments/enhanced-data). description: > Object that contains information about the customer and their shipping address. Contains parameters required for [Level 3 and CEDP transactions](https://docs.payroc.com/knowledge/card-payments/enhanced-data). title: shipping contactMethod: oneOf: - type: object properties: type: type: string enum: - email description: 'Discriminator value: email' value: type: string maxLength: 50 description: Email address. required: - type - value description: email variant - type: object properties: type: type: string enum: - phone description: 'Discriminator value: phone' value: type: string maxLength: 15 description: Phone number. required: - type - value description: phone variant - type: object properties: type: type: string enum: - mobile description: 'Discriminator value: mobile' value: type: string maxLength: 15 description: Mobile number. required: - type - value description: mobile variant - type: object properties: type: type: string enum: - fax description: 'Discriminator value: fax' value: type: string maxLength: 15 description: Fax number. required: - type - value description: fax variant discriminator: propertyName: type title: contactMethod CustomerNotificationLanguage: 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: CustomerNotificationLanguage customer: type: object properties: firstName: type: string minLength: 0 maxLength: 60 description: Customer's first name. lastName: type: string minLength: 0 maxLength: 60 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 minLength: 0 maxLength: 48 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. Required for [Level 2, Level 3, and CEDP transactions](https://docs.payroc.com/knowledge/card-payments/enhanced-data). billingAddress: $ref: '#/components/schemas/address' description: >- Object that contains information about the address that the card is registered to. shippingAddress: $ref: '#/components/schemas/shipping' 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/CustomerNotificationLanguage' 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. Contains parameters required for [Level 2, Level 3, and CEDP transactions](https://docs.payroc.com/knowledge/card-payments/enhanced-data). title: customer IpAddressType: type: string enum: - ipv4 - ipv6 description: Internet protocol version of the IP address. title: IpAddressType ipAddress: type: object properties: type: $ref: '#/components/schemas/IpAddressType' description: Internet protocol version of the IP address. value: type: string description: IP address of the device. required: - type - value description: Object that contains the IP address of the device that sent the request. title: ipAddress SchemasCredentialOnFileMitAgreement: type: string enum: - unscheduled - recurring - installment description: > Indicates how the merchant can use the customer's card details to run future card transactions, as agreed with the customer. If you send a value for the **mitAgreement** parameter, you must also include the **[standingInstructions](https://docs.payroc.com/api/schema/card-payments/payments/create#request.body.order.standingInstructions)** object in your request. - `unscheduled` - Transactions for a fixed or variable amount that the merchant runs at a certain predefined event. - `recurring` - Transactions for a fixed amount that the merchant runs at regular intervals, for example, monthly. Recurring transactions don’t have a fixed duration and run until the customer cancels the agreement. - `installment` - Transactions for a fixed amount that the merchant runs at regular intervals, for example, monthly. Installment transactions have a fixed duration. **Note:** If you send a value for **mitAgreement**, you must send the **standingInstructions** object in the **paymentOrder** object. title: SchemasCredentialOnFileMitAgreement schemas-credentialOnFile: type: object properties: externalVault: type: boolean default: false description: >- Indicates if the merchant uses a third-party vault to store the customer’s payment details. tokenize: type: boolean description: >- Indicates if our gateway should tokenize the customer’s payment details as part of the transaction. secureTokenId: type: string minLength: 0 maxLength: 200 description: > Unique identifier that the merchant creates for the secure token that represents the customer’s payment details. **Note:** If you do not send a value for the **secureTokenId** parameter, our gateway generates a unique identifier for the token. mitAgreement: $ref: '#/components/schemas/SchemasCredentialOnFileMitAgreement' description: > Indicates how the merchant can use the customer's card details to run future card transactions, as agreed with the customer. If you send a value for the **mitAgreement** parameter, you must also include the **[standingInstructions](https://docs.payroc.com/api/schema/card-payments/payments/create#request.body.order.standingInstructions)** object in your request. - `unscheduled` - Transactions for a fixed or variable amount that the merchant runs at a certain predefined event. - `recurring` - Transactions for a fixed amount that the merchant runs at regular intervals, for example, monthly. Recurring transactions don’t have a fixed duration and run until the customer cancels the agreement. - `installment` - Transactions for a fixed amount that the merchant runs at regular intervals, for example, monthly. Installment transactions have a fixed duration. **Note:** If you send a value for **mitAgreement**, you must send the **standingInstructions** object in the **paymentOrder** object. description: >- Object that contains information about saving the customer’s payment details. title: schemas-credentialOnFile EbtDetailsBenefitCategory: type: string enum: - cash - foodStamp description: > Indicates if the balance relates to an EBT Cash account or an EBT SNAP account. - `cash` – EBT Cash - `foodStamp` – EBT SNAP title: EbtDetailsBenefitCategory ebtDetails: type: object properties: benefitCategory: $ref: '#/components/schemas/EbtDetailsBenefitCategory' description: > Indicates if the balance relates to an EBT Cash account or an EBT SNAP account. - `cash` – EBT Cash - `foodStamp` – EBT SNAP withdrawal: type: boolean description: > Indicates whether the customer wants to withdraw cash. **Note:** Cash withdrawals are available only from EBT Cash accounts. required: - benefitCategory description: >- Object that contains information about the Electronic Benefit Transfer (EBT) transaction. title: ebtDetails CustomizationOptionsEntryMethod: type: string enum: - deviceRead - manualEntry - deviceReadOrManualEntry default: deviceRead description: > Indicates how you want the device to capture the card details. - `deviceRead` - Device prompts the cardholder to tap, swipe, or insert their card. - `manualEntry` - Device prompts the merchant or cardholder to manually enter card details. - `deviceReadOrManualEntry` - Device prompts the cardholder to tap, swipe, or insert their card. The device also displays an option for the merchant or cardholder to manually enter card details. title: CustomizationOptionsEntryMethod CustomizationOptionsClosedLoopOptions: oneOf: - type: object properties: type: type: string enum: - mifare description: 'Discriminator value: mifare' required: - type description: mifare variant discriminator: propertyName: type description: > Polymorphic object that indicates the type of closed-loop card that the merchant accepts. title: CustomizationOptionsClosedLoopOptions customizationOptions: type: object properties: ebtDetails: $ref: '#/components/schemas/ebtDetails' entryMethod: $ref: '#/components/schemas/CustomizationOptionsEntryMethod' default: deviceRead description: > Indicates how you want the device to capture the card details. - `deviceRead` - Device prompts the cardholder to tap, swipe, or insert their card. - `manualEntry` - Device prompts the merchant or cardholder to manually enter card details. - `deviceReadOrManualEntry` - Device prompts the cardholder to tap, swipe, or insert their card. The device also displays an option for the merchant or cardholder to manually enter card details. closedLoopOptions: $ref: '#/components/schemas/CustomizationOptionsClosedLoopOptions' description: > Polymorphic object that indicates the type of closed-loop card that the merchant accepts. description: >- Object that contains available options to customize certain aspects of an instruction. title: customizationOptions paymentInstructionRequest: type: object properties: operator: type: string minLength: 0 maxLength: 50 description: Operator who initiated the request. processingTerminalId: type: string minLength: 4 maxLength: 50 description: Unique identifier that we assigned to the terminal. order: $ref: '#/components/schemas/paymentInstructionOrder' customer: $ref: '#/components/schemas/customer' ipAddress: $ref: '#/components/schemas/ipAddress' credentialOnFile: $ref: '#/components/schemas/schemas-credentialOnFile' customizationOptions: $ref: '#/components/schemas/customizationOptions' autoCapture: type: boolean default: true description: > Indicates if we should automatically capture the payment amount. - `true` - Run a sale and automatically capture the transaction. - `false`- Run a pre-authorization and capture the transaction later. **Note:** If you send `false` and the terminal doesn't support pre-authorization, we set the transaction's status to pending. The merchant must capture the transaction to take payment from the customer. processAsSale: type: boolean default: false description: > Indicates if we should immediately settle the sale transaction. The merchant cannot adjust the transaction if we immediately settle it. **Note:** If the value for **processAsSale** is `true`, the gateway ignores the value in **autoCapture**. required: - processingTerminalId - order description: >- Object that contains the instructions for initiating a payment on a physical device. title: paymentInstructionRequest PaymentInstructionStatus: type: string enum: - canceled - completed - failure - inProgress description: > Indicates the current status of the instruction. - `canceled` – The instruction was canceled before it was completed. - `completed` – The instruction has completed. Use the link object to check the resource. - `failure` – The instruction failed. Check the errorMessage field for more information. - `inProgress` – The instruction is currently in progress. title: PaymentInstructionStatus 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 paymentInstruction: type: object properties: status: $ref: '#/components/schemas/PaymentInstructionStatus' description: > Indicates the current status of the instruction. - `canceled` – The instruction was canceled before it was completed. - `completed` – The instruction has completed. Use the link object to check the resource. - `failure` – The instruction failed. Check the errorMessage field for more information. - `inProgress` – The instruction is currently in progress. errorMessage: type: string description: | Description of the error that caused the instruction to fail. **Note:** We return this field only if the status is `failure`. link: $ref: '#/components/schemas/link' paymentInstructionId: type: string minLength: 1 maxLength: 36 description: Unique identifier that we assigned to the payment instruction. required: - status - paymentInstructionId title: paymentInstruction ErrorsItems: type: object properties: message: type: string description: Error message title: ErrorsItems ```### Example request " \ -H "Content-Type: application/json" \ -d '{ "processingTerminalId": "1234001", "order": { "orderId": "OrderRef6543", "amount": 4999, "currency": "USD" }, "operator": "Jane", "customizationOptions": { "entryMethod": "deviceRead" }, "autoCapture": true }' ```` **`Payment Instruction`** ```python Payment Instruction import requests url = "https://api.payroc.com/v1/devices/1850010868/payment-instructions" payload = { "processingTerminalId": "1234001", "order": { "orderId": "OrderRef6543", "amount": 4999, "currency": "USD" }, "operator": "Jane", "customizationOptions": { "entryMethod": "deviceRead" }, "autoCapture": True } headers = { "Idempotency-Key": "8e03978e-40d5-43e8-bc93-6894a57f9324", "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` **`Payment Instruction`** ```javascript Payment Instruction const url = 'https://api.payroc.com/v1/devices/1850010868/payment-instructions'; const options = { method: 'POST', headers: { 'Idempotency-Key': '8e03978e-40d5-43e8-bc93-6894a57f9324', Authorization: 'Bearer ', 'Content-Type': 'application/json' }, body: '{"processingTerminalId":"1234001","order":{"orderId":"OrderRef6543","amount":4999,"currency":"USD"},"operator":"Jane","customizationOptions":{"entryMethod":"deviceRead"},"autoCapture":true}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` **`Payment Instruction`** ```go Payment Instruction package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.payroc.com/v1/devices/1850010868/payment-instructions" payload := strings.NewReader("{\n \"processingTerminalId\": \"1234001\",\n \"order\": {\n \"orderId\": \"OrderRef6543\",\n \"amount\": 4999,\n \"currency\": \"USD\"\n },\n \"operator\": \"Jane\",\n \"customizationOptions\": {\n \"entryMethod\": \"deviceRead\"\n },\n \"autoCapture\": true\n}") req, _ := http.NewRequest("POST", url, payload) 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)) } ``` **`Payment Instruction`** ```ruby Payment Instruction require 'uri' require 'net/http' url = URI("https://api.payroc.com/v1/devices/1850010868/payment-instructions") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Idempotency-Key"] = '8e03978e-40d5-43e8-bc93-6894a57f9324' request["Authorization"] = 'Bearer ' request["Content-Type"] = 'application/json' request.body = "{\n \"processingTerminalId\": \"1234001\",\n \"order\": {\n \"orderId\": \"OrderRef6543\",\n \"amount\": 4999,\n \"currency\": \"USD\"\n },\n \"operator\": \"Jane\",\n \"customizationOptions\": {\n \"entryMethod\": \"deviceRead\"\n },\n \"autoCapture\": true\n}" response = http.request(request) puts response.read_body ``` **`Payment Instruction`** ```java Payment Instruction import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.payroc.com/v1/devices/1850010868/payment-instructions") .header("Idempotency-Key", "8e03978e-40d5-43e8-bc93-6894a57f9324") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{\n \"processingTerminalId\": \"1234001\",\n \"order\": {\n \"orderId\": \"OrderRef6543\",\n \"amount\": 4999,\n \"currency\": \"USD\"\n },\n \"operator\": \"Jane\",\n \"customizationOptions\": {\n \"entryMethod\": \"deviceRead\"\n },\n \"autoCapture\": true\n}") .asString(); ``` **`Payment Instruction`** ```php Payment Instruction request('POST', 'https://api.payroc.com/v1/devices/1850010868/payment-instructions', [ 'body' => '{ "processingTerminalId": "1234001", "order": { "orderId": "OrderRef6543", "amount": 4999, "currency": "USD" }, "operator": "Jane", "customizationOptions": { "entryMethod": "deviceRead" }, "autoCapture": true }', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', 'Idempotency-Key' => '8e03978e-40d5-43e8-bc93-6894a57f9324', ], ]); echo $response->getBody(); ``` **`Payment Instruction`** ```csharp Payment Instruction using RestSharp; var client = new RestClient("https://api.payroc.com/v1/devices/1850010868/payment-instructions"); var request = new RestRequest(Method.POST); request.AddHeader("Idempotency-Key", "8e03978e-40d5-43e8-bc93-6894a57f9324"); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"processingTerminalId\": \"1234001\",\n \"order\": {\n \"orderId\": \"OrderRef6543\",\n \"amount\": 4999,\n \"currency\": \"USD\"\n },\n \"operator\": \"Jane\",\n \"customizationOptions\": {\n \"entryMethod\": \"deviceRead\"\n },\n \"autoCapture\": true\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` **`Payment Instruction`** ````swift Payment Instruction import Foundation let headers = [ "Idempotency-Key": "8e03978e-40d5-43e8-bc93-6894a57f9324", "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = [ "processingTerminalId": "1234001", "order": [ "orderId": "OrderRef6543", "amount": 4999, "currency": "USD" ], "operator": "Jane", "customizationOptions": ["entryMethod": "deviceRead"], "autoCapture": true ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.payroc.com/v1/devices/1850010868/payment-instructions")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data 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 send the payment instruction to the device. **Note:** The response returns a value of `inProgress` for the status field and an identifier for the instruction that you can use to check the status of the instruction. To get a link to view the details of the payment, go to Step 2. Use this method to submit an instruction request to initiate a sale on a payment device. In the request, include the order amount and currency. When you send a successful request, our gateway returns information about the payment instruction and a paymentInstructionId, which you need for the following methods: - [Retrieve payment instruction](https://docs.payroc.com/api/schema/payroc-cloud/payment-instructions/retrieve) - View the details of the payment instruction. - [Cancel payment instruction](https://docs.payroc.com/api/schema/payroc-cloud/payment-instructions/delete) - Cancel the payment instruction. tags: - subpackage_payrocCloud/paymentInstructions parameters: - name: serialNumber in: path description: Serial number of the merchant’s payment device. required: true schema: type: string minLength: 1 maxLength: 64 - 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: '202': description: Successful request. We accepted the payment instruction. content: application/json: schema: $ref: '#/components/schemas/paymentInstruction' '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/paymentInstructionRequest' servers: - url: https://api.payroc.com/v1 description: Production - url: https://api.uat.payroc.com/v1 description: UAT 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' 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 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 exclusiveMinimum: 0 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 maximum: 100 exclusiveMinimum: 0 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 exclusiveMinimum: 0 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 maximum: 100 exclusiveMinimum: 0 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 maximum: 100 exclusiveMinimum: 0 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 exclusiveMinimum: 0 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 HealthcareExpenseType: type: string enum: - copay - clinic - dental - prescription - transit - vision description: Type of healthcare expense. title: HealthcareExpenseType healthcareExpense: type: object properties: type: $ref: '#/components/schemas/HealthcareExpenseType' description: Type of healthcare expense. amount: type: integer format: int64 exclusiveMinimum: 0 description: >- Amount of the healthcare expense. The value is in the currency's lowest denomination, for example, cents. required: - type - amount description: Object that contains information about a healthcare expense. title: healthcareExpense taxRate: type: object properties: rate: type: number format: double minimum: 0 maximum: 99.99999 description: > Tax percentage for the transaction. Required for [Level 3 and CEDP transactions](https://docs.payroc.com/knowledge/card-payments/enhanced-data). name: type: string minLength: 1 maxLength: 64 description: >- Name of the tax. A tax validation on the stored rate for the tax name is performed. required: - rate - name title: taxRate breakdownForPaymentInstructions: 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. Required for [Level 2, Level 3, and CEDP transactions](https://docs.payroc.com/knowledge/card-payments/enhanced-data). 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. healthcareExpenses: type: array items: $ref: '#/components/schemas/healthcareExpense' description: >- Array of healthcareExpense objects that contain information about healthcare expenses. taxes: type: array items: $ref: '#/components/schemas/taxRate' description: List of taxes. required: - subtotal description: Object that contains information about the breakdown of the transaction. title: breakdownForPaymentInstructions paymentInstructionOrder: type: object properties: orderId: type: string minLength: 1 maxLength: 24 description: Unique identifier that the merchant assigns to the transaction. 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](https://www.iso.org/iso-8601-date-and-time-format.html) format. description: type: string minLength: 0 maxLength: 1024 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' acceptPartialAmount: type: boolean default: false description: > Indicates if the merchant accepts a partial authorization for this transaction. - `true` — If the issuer cannot approve the full amount, the gateway accepts a partial authorization and returns the approved amount. The integrator is responsible for collecting the remaining balance via a follow-up payment. - `false` — Standard authorization behavior. If the issuer cannot approve the full amount, the transaction is declined. **Note:** When this field is omitted, the default is `false` and standard authorization behavior applies. breakdown: $ref: '#/components/schemas/breakdownForPaymentInstructions' required: - orderId - amount - currency description: Object that contains information about the payment. title: paymentInstructionOrder address: type: object properties: address1: type: string maxLength: 150 description: Address line 1. address2: type: string maxLength: 150 description: Address line 2. address3: type: string maxLength: 150 description: Address line 3. city: type: string maxLength: 50 description: City. state: type: string maxLength: 50 description: Name of the state or state abbreviation. country: type: string minLength: 2 maxLength: 2 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 maxLength: 10 description: Zip code or postal code. required: - address1 - city - state - country - postalCode description: Object that contains information about the address. title: address shipping: type: object properties: recipientName: type: string minLength: 0 maxLength: 50 description: > Recipient's name. Required for [Level 3 and CEDP transactions](https://docs.payroc.com/knowledge/card-payments/enhanced-data). address: $ref: '#/components/schemas/address' description: > Object that contains information about the shipping address. Required for [Level 3 and CEDP transactions](https://docs.payroc.com/knowledge/card-payments/enhanced-data). description: > Object that contains information about the customer and their shipping address. Contains parameters required for [Level 3 and CEDP transactions](https://docs.payroc.com/knowledge/card-payments/enhanced-data). title: shipping contactMethod: oneOf: - type: object properties: type: type: string enum: - email description: 'Discriminator value: email' value: type: string maxLength: 50 description: Email address. required: - type - value description: email variant - type: object properties: type: type: string enum: - phone description: 'Discriminator value: phone' value: type: string maxLength: 15 description: Phone number. required: - type - value description: phone variant - type: object properties: type: type: string enum: - mobile description: 'Discriminator value: mobile' value: type: string maxLength: 15 description: Mobile number. required: - type - value description: mobile variant - type: object properties: type: type: string enum: - fax description: 'Discriminator value: fax' value: type: string maxLength: 15 description: Fax number. required: - type - value description: fax variant discriminator: propertyName: type title: contactMethod CustomerNotificationLanguage: 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: CustomerNotificationLanguage customer: type: object properties: firstName: type: string minLength: 0 maxLength: 60 description: Customer's first name. lastName: type: string minLength: 0 maxLength: 60 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 minLength: 0 maxLength: 48 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. Required for [Level 2, Level 3, and CEDP transactions](https://docs.payroc.com/knowledge/card-payments/enhanced-data). billingAddress: $ref: '#/components/schemas/address' description: >- Object that contains information about the address that the card is registered to. shippingAddress: $ref: '#/components/schemas/shipping' 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/CustomerNotificationLanguage' 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. Contains parameters required for [Level 2, Level 3, and CEDP transactions](https://docs.payroc.com/knowledge/card-payments/enhanced-data). title: customer IpAddressType: type: string enum: - ipv4 - ipv6 description: Internet protocol version of the IP address. title: IpAddressType ipAddress: type: object properties: type: $ref: '#/components/schemas/IpAddressType' description: Internet protocol version of the IP address. value: type: string description: IP address of the device. required: - type - value description: Object that contains the IP address of the device that sent the request. title: ipAddress SchemasCredentialOnFileMitAgreement: type: string enum: - unscheduled - recurring - installment description: > Indicates how the merchant can use the customer's card details to run future card transactions, as agreed with the customer. If you send a value for the **mitAgreement** parameter, you must also include the **[standingInstructions](https://docs.payroc.com/api/schema/card-payments/payments/create#request.body.order.standingInstructions)** object in your request. - `unscheduled` - Transactions for a fixed or variable amount that the merchant runs at a certain predefined event. - `recurring` - Transactions for a fixed amount that the merchant runs at regular intervals, for example, monthly. Recurring transactions don’t have a fixed duration and run until the customer cancels the agreement. - `installment` - Transactions for a fixed amount that the merchant runs at regular intervals, for example, monthly. Installment transactions have a fixed duration. **Note:** If you send a value for **mitAgreement**, you must send the **standingInstructions** object in the **paymentOrder** object. title: SchemasCredentialOnFileMitAgreement schemas-credentialOnFile: type: object properties: externalVault: type: boolean default: false description: >- Indicates if the merchant uses a third-party vault to store the customer’s payment details. tokenize: type: boolean description: >- Indicates if our gateway should tokenize the customer’s payment details as part of the transaction. secureTokenId: type: string minLength: 0 maxLength: 200 description: > Unique identifier that the merchant creates for the secure token that represents the customer’s payment details. **Note:** If you do not send a value for the **secureTokenId** parameter, our gateway generates a unique identifier for the token. mitAgreement: $ref: '#/components/schemas/SchemasCredentialOnFileMitAgreement' description: > Indicates how the merchant can use the customer's card details to run future card transactions, as agreed with the customer. If you send a value for the **mitAgreement** parameter, you must also include the **[standingInstructions](https://docs.payroc.com/api/schema/card-payments/payments/create#request.body.order.standingInstructions)** object in your request. - `unscheduled` - Transactions for a fixed or variable amount that the merchant runs at a certain predefined event. - `recurring` - Transactions for a fixed amount that the merchant runs at regular intervals, for example, monthly. Recurring transactions don’t have a fixed duration and run until the customer cancels the agreement. - `installment` - Transactions for a fixed amount that the merchant runs at regular intervals, for example, monthly. Installment transactions have a fixed duration. **Note:** If you send a value for **mitAgreement**, you must send the **standingInstructions** object in the **paymentOrder** object. description: >- Object that contains information about saving the customer’s payment details. title: schemas-credentialOnFile EbtDetailsBenefitCategory: type: string enum: - cash - foodStamp description: > Indicates if the balance relates to an EBT Cash account or an EBT SNAP account. - `cash` – EBT Cash - `foodStamp` – EBT SNAP title: EbtDetailsBenefitCategory ebtDetails: type: object properties: benefitCategory: $ref: '#/components/schemas/EbtDetailsBenefitCategory' description: > Indicates if the balance relates to an EBT Cash account or an EBT SNAP account. - `cash` – EBT Cash - `foodStamp` – EBT SNAP withdrawal: type: boolean description: > Indicates whether the customer wants to withdraw cash. **Note:** Cash withdrawals are available only from EBT Cash accounts. required: - benefitCategory description: >- Object that contains information about the Electronic Benefit Transfer (EBT) transaction. title: ebtDetails CustomizationOptionsEntryMethod: type: string enum: - deviceRead - manualEntry - deviceReadOrManualEntry default: deviceRead description: > Indicates how you want the device to capture the card details. - `deviceRead` - Device prompts the cardholder to tap, swipe, or insert their card. - `manualEntry` - Device prompts the merchant or cardholder to manually enter card details. - `deviceReadOrManualEntry` - Device prompts the cardholder to tap, swipe, or insert their card. The device also displays an option for the merchant or cardholder to manually enter card details. title: CustomizationOptionsEntryMethod CustomizationOptionsClosedLoopOptions: oneOf: - type: object properties: type: type: string enum: - mifare description: 'Discriminator value: mifare' required: - type description: mifare variant discriminator: propertyName: type description: > Polymorphic object that indicates the type of closed-loop card that the merchant accepts. title: CustomizationOptionsClosedLoopOptions customizationOptions: type: object properties: ebtDetails: $ref: '#/components/schemas/ebtDetails' entryMethod: $ref: '#/components/schemas/CustomizationOptionsEntryMethod' default: deviceRead description: > Indicates how you want the device to capture the card details. - `deviceRead` - Device prompts the cardholder to tap, swipe, or insert their card. - `manualEntry` - Device prompts the merchant or cardholder to manually enter card details. - `deviceReadOrManualEntry` - Device prompts the cardholder to tap, swipe, or insert their card. The device also displays an option for the merchant or cardholder to manually enter card details. closedLoopOptions: $ref: '#/components/schemas/CustomizationOptionsClosedLoopOptions' description: > Polymorphic object that indicates the type of closed-loop card that the merchant accepts. description: >- Object that contains available options to customize certain aspects of an instruction. title: customizationOptions paymentInstructionRequest: type: object properties: operator: type: string minLength: 0 maxLength: 50 description: Operator who initiated the request. processingTerminalId: type: string minLength: 4 maxLength: 50 description: Unique identifier that we assigned to the terminal. order: $ref: '#/components/schemas/paymentInstructionOrder' customer: $ref: '#/components/schemas/customer' ipAddress: $ref: '#/components/schemas/ipAddress' credentialOnFile: $ref: '#/components/schemas/schemas-credentialOnFile' customizationOptions: $ref: '#/components/schemas/customizationOptions' autoCapture: type: boolean default: true description: > Indicates if we should automatically capture the payment amount. - `true` - Run a sale and automatically capture the transaction. - `false`- Run a pre-authorization and capture the transaction later. **Note:** If you send `false` and the terminal doesn't support pre-authorization, we set the transaction's status to pending. The merchant must capture the transaction to take payment from the customer. processAsSale: type: boolean default: false description: > Indicates if we should immediately settle the sale transaction. The merchant cannot adjust the transaction if we immediately settle it. **Note:** If the value for **processAsSale** is `true`, the gateway ignores the value in **autoCapture**. required: - processingTerminalId - order description: >- Object that contains the instructions for initiating a payment on a physical device. title: paymentInstructionRequest PaymentInstructionStatus: type: string enum: - canceled - completed - failure - inProgress description: > Indicates the current status of the instruction. - `canceled` – The instruction was canceled before it was completed. - `completed` – The instruction has completed. Use the link object to check the resource. - `failure` – The instruction failed. Check the errorMessage field for more information. - `inProgress` – The instruction is currently in progress. title: PaymentInstructionStatus 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 paymentInstruction: type: object properties: status: $ref: '#/components/schemas/PaymentInstructionStatus' description: > Indicates the current status of the instruction. - `canceled` – The instruction was canceled before it was completed. - `completed` – The instruction has completed. Use the link object to check the resource. - `failure` – The instruction failed. Check the errorMessage field for more information. - `inProgress` – The instruction is currently in progress. errorMessage: type: string description: | Description of the error that caused the instruction to fail. **Note:** We return this field only if the status is `failure`. link: $ref: '#/components/schemas/link' paymentInstructionId: type: string minLength: 1 maxLength: 36 description: Unique identifier that we assigned to the payment instruction. required: - status - paymentInstructionId title: paymentInstruction ErrorsItems: type: object properties: message: type: string description: Error message title: ErrorsItems ```## Response parameters **Note:** Wait until you receive a response from our gateway before you send another request. ### Request parameters To create your request, use the following parameters: Use this method to retrieve information about a payment instruction. To retrieve a payment instruction, you need its paymentInstructionId. Our gateway returned the paymentInstructionId in the response of the [Submit Payment Instruction](https://docs.payroc.com/api/schema/payroc-cloud/payment-instructions/submit) method. Our gateway returns the status of the payment instruction. If the payment device completed the payment instruction, the response also includes a link to the payment. tags: - subpackage_payrocCloud/paymentInstructions parameters: - name: paymentInstructionId in: path description: Unique identifier that we assigned to the payment instruction. required: true schema: type: string minLength: 1 maxLength: 36 responses: '200': description: >- Successful request. Returns the current status of the requested payment instruction. content: application/json: schema: $ref: '#/components/schemas/paymentInstruction' '400': description: Invalid request 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' '500': description: An error has occured content: application/json: schema: $ref: '#/components/schemas/500' servers: - url: https://api.payroc.com/v1 description: Production - url: https://api.uat.payroc.com/v1 description: UAT 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' '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' PaymentInstructionStatus: type: string enum: - canceled - completed - failure - inProgress description: > Indicates the current status of the instruction. - `canceled` – The instruction was canceled before it was completed. - `completed` – The instruction has completed. Use the link object to check the resource. - `failure` – The instruction failed. Check the errorMessage field for more information. - `inProgress` – The instruction is currently in progress. title: PaymentInstructionStatus 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 paymentInstruction: type: object properties: status: $ref: '#/components/schemas/PaymentInstructionStatus' description: > Indicates the current status of the instruction. - `canceled` – The instruction was canceled before it was completed. - `completed` – The instruction has completed. Use the link object to check the resource. - `failure` – The instruction failed. Check the errorMessage field for more information. - `inProgress` – The instruction is currently in progress. errorMessage: type: string description: | Description of the error that caused the instruction to fail. **Note:** We return this field only if the status is `failure`. link: $ref: '#/components/schemas/link' paymentInstructionId: type: string minLength: 1 maxLength: 36 description: Unique identifier that we assigned to the payment instruction. required: - status - paymentInstructionId title: paymentInstruction ErrorsItems: type: object properties: message: type: string description: Error message title: ErrorsItems ```### Example request " ```` **`Payment instruction`** ```python Payment instruction import requests url = "https://api.payroc.com/v1/payment-instructions/e743a9165d134678a9100ebba3b29597" headers = {"Authorization": "Bearer "} response = requests.get(url, headers=headers) print(response.json()) ``` **`Payment instruction`** ```javascript Payment instruction const url = 'https://api.payroc.com/v1/payment-instructions/e743a9165d134678a9100ebba3b29597'; const options = {method: 'GET', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` **`Payment instruction`** ```go Payment instruction package main import ( "fmt" "net/http" "io" ) func main() { url := "https://api.payroc.com/v1/payment-instructions/e743a9165d134678a9100ebba3b29597" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("Authorization", "Bearer ") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` **`Payment instruction`** ```ruby Payment instruction require 'uri' require 'net/http' url = URI("https://api.payroc.com/v1/payment-instructions/e743a9165d134678a9100ebba3b29597") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) request["Authorization"] = 'Bearer ' response = http.request(request) puts response.read_body ``` **`Payment instruction`** ```java Payment instruction import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("https://api.payroc.com/v1/payment-instructions/e743a9165d134678a9100ebba3b29597") .header("Authorization", "Bearer ") .asString(); ``` **`Payment instruction`** ```php Payment instruction request('GET', 'https://api.payroc.com/v1/payment-instructions/e743a9165d134678a9100ebba3b29597', [ 'headers' => [ 'Authorization' => 'Bearer ', ], ]); echo $response->getBody(); ``` **`Payment instruction`** ```csharp Payment instruction using RestSharp; var client = new RestClient("https://api.payroc.com/v1/payment-instructions/e743a9165d134678a9100ebba3b29597"); var request = new RestRequest(Method.GET); request.AddHeader("Authorization", "Bearer "); IRestResponse response = client.Execute(request); ``` **`Payment instruction`** ````swift Payment instruction import Foundation let headers = ["Authorization": "Bearer "] let request = NSMutableURLRequest(url: NSURL(string: "https://api.payroc.com/v1/payment-instructions/e743a9165d134678a9100ebba3b29597")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "GET" 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 return the details of the payment instruction, including HATEOAS links to check the details of the payment. Use the HATEOAS links to get the paymentId, which you need in Step 3. If the status of the payment instruction is `inProgress`, our gateway waits up to a minute for the status to change before it returns a response. Use this method to retrieve information about a payment instruction. To retrieve a payment instruction, you need its paymentInstructionId. Our gateway returned the paymentInstructionId in the response of the [Submit Payment Instruction](https://docs.payroc.com/api/schema/payroc-cloud/payment-instructions/submit) method. Our gateway returns the status of the payment instruction. If the payment device completed the payment instruction, the response also includes a link to the payment. tags: - subpackage_payrocCloud/paymentInstructions parameters: - name: paymentInstructionId in: path description: Unique identifier that we assigned to the payment instruction. required: true schema: type: string minLength: 1 maxLength: 36 responses: '200': description: >- Successful request. Returns the current status of the requested payment instruction. content: application/json: schema: $ref: '#/components/schemas/paymentInstruction' '400': description: Invalid request 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' '500': description: An error has occured content: application/json: schema: $ref: '#/components/schemas/500' servers: - url: https://api.payroc.com/v1 description: Production - url: https://api.uat.payroc.com/v1 description: UAT 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' '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' PaymentInstructionStatus: type: string enum: - canceled - completed - failure - inProgress description: > Indicates the current status of the instruction. - `canceled` – The instruction was canceled before it was completed. - `completed` – The instruction has completed. Use the link object to check the resource. - `failure` – The instruction failed. Check the errorMessage field for more information. - `inProgress` – The instruction is currently in progress. title: PaymentInstructionStatus 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 paymentInstruction: type: object properties: status: $ref: '#/components/schemas/PaymentInstructionStatus' description: > Indicates the current status of the instruction. - `canceled` – The instruction was canceled before it was completed. - `completed` – The instruction has completed. Use the link object to check the resource. - `failure` – The instruction failed. Check the errorMessage field for more information. - `inProgress` – The instruction is currently in progress. errorMessage: type: string description: | Description of the error that caused the instruction to fail. **Note:** We return this field only if the status is `failure`. link: $ref: '#/components/schemas/link' paymentInstructionId: type: string minLength: 1 maxLength: 36 description: Unique identifier that we assigned to the payment instruction. required: - status - paymentInstructionId title: paymentInstruction ErrorsItems: type: object properties: message: type: string description: Error message title: ErrorsItems ```### Example response Use this method to retrieve information about a card payment. To retrieve a payment, 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. **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. Our gateway returns the following information about the payment: - Order details, including the transaction amount and when it was processed. - Payment card details, including the masked card number, expiry date, and payment method. - Cardholder details, including their contact information and shipping address. - Payment details, including the payment type, status, and response. If the merchant saved the customer's card details, our gateway returns a secureTokenID, which you can use to perform follow-on actions. tags: - 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 minLength: 10 maxLength: 10 responses: '200': description: Successful request. Returns the payment. content: application/json: schema: $ref: '#/components/schemas/retrievedPayment' '400': description: Invalid request 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' '500': description: An error has occured content: application/json: schema: $ref: '#/components/schemas/500' servers: - url: https://api.payroc.com/v1 description: Production - url: https://api.uat.payroc.com/v1 description: UAT 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' '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' 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 minLength: 3 maxLength: 3 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: >- Indicates if this payment is the first payment or if it is a subsequent payment. title: StandingInstructionsSequence StandingInstructionsProcessingModel: type: string enum: - unscheduled - recurring - installment description: > Indicates the type of payment schedule. - '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 minLength: 10 maxLength: 10 description: > Unique identifier of the first payment. **Note:** We recommend that you always send a value for the **paymentId** parameter. cardSchemeReferenceId: type: string minLength: 1 maxLength: 64 description: Identifier that the card brand assigned to the first payment. description: Object that contains information about the first payment. title: firstTxnReferenceData standingInstructions: type: object properties: sequence: $ref: '#/components/schemas/StandingInstructionsSequence' description: >- Indicates if this payment is the first payment or if it is a subsequent payment. processingModel: $ref: '#/components/schemas/StandingInstructionsProcessingModel' description: > Indicates the type of payment schedule. - '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 first payment. required: - sequence - processingModel description: > Object that contains information about repeat payments. Include this object if the payment is part of a recurring billing schedule and you don't use our [subscriptions](https://docs.payroc.com/guides/take-payments/repeat-payments/use-our-gateway) feature. title: standingInstructions 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 exclusiveMinimum: 0 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 maximum: 100 exclusiveMinimum: 0 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 exclusiveMinimum: 0 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 maximum: 100 exclusiveMinimum: 0 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 maximum: 100 exclusiveMinimum: 0 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 exclusiveMinimum: 0 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 HealthcareExpenseType: type: string enum: - copay - clinic - dental - prescription - transit - vision description: Type of healthcare expense. title: HealthcareExpenseType healthcareExpense: type: object properties: type: $ref: '#/components/schemas/HealthcareExpenseType' description: Type of healthcare expense. amount: type: integer format: int64 exclusiveMinimum: 0 description: >- Amount of the healthcare expense. The value is in the currency's lowest denomination, for example, cents. required: - type - amount description: Object that contains information about a healthcare expense. title: healthcareExpense retrievedTax: type: object properties: name: type: string minLength: 1 maxLength: 64 description: Name of the tax. rate: type: number format: double minimum: 0 maximum: 99.99999 description: Tax percentage for the transaction. amount: type: integer format: int64 exclusiveMinimum: 0 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 convenienceFee: type: object properties: amount: type: integer format: int64 exclusiveMinimum: 0 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 lineItem: type: object properties: commodityCode: type: string minLength: 0 maxLength: 45 description: > Commodity code of the item. Required for [Level 3 and CEDP transactions](https://docs.payroc.com/knowledge/card-payments/enhanced-data). productCode: type: string minLength: 0 maxLength: 45 description: > Product code of the item. Required for [Level 3 and CEDP transactions](https://docs.payroc.com/knowledge/card-payments/enhanced-data). description: type: string minLength: 0 maxLength: 250 description: > Description of the item. Required for [Level 3 and CEDP transactions](https://docs.payroc.com/knowledge/card-payments/enhanced-data). unitOfMeasure: $ref: '#/components/schemas/unitOfMeasure' description: > Unit of measurement for the item. Required for [Level 3 and CEDP transactions](https://docs.payroc.com/knowledge/card-payments/enhanced-data). Also required for Level 2 (American Express only). unitPrice: type: integer format: int64 exclusiveMinimum: 0 description: > Price of each unit. Required for [Level 3 and CEDP transactions](https://docs.payroc.com/knowledge/card-payments/enhanced-data). quantity: type: number format: double exclusiveMinimum: 0 description: > Number of units. Required for [Level 3 and CEDP transactions](https://docs.payroc.com/knowledge/card-payments/enhanced-data). discountRate: type: number format: double exclusiveMinimum: 0 description: > Discount rate that the merchant applies to the item. Required for [Level 3 and CEDP transactions](https://docs.payroc.com/knowledge/card-payments/enhanced-data). taxes: type: array items: $ref: '#/components/schemas/retrievedTax' description: > Array of objects that contain information about each tax that applies to the item. Required for [Level 3 and CEDP transactions](https://docs.payroc.com/knowledge/card-payments/enhanced-data). required: - unitPrice - quantity description: > List of line items. Contains parameters required for [Level 3 and CEDP transactions](https://docs.payroc.com/knowledge/card-payments/enhanced-data). 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. Required for [Level 2, Level 3, and CEDP transactions](https://docs.payroc.com/knowledge/card-payments/enhanced-data). 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. healthcareExpenses: type: array items: $ref: '#/components/schemas/healthcareExpense' description: >- Array of healthcareExpense objects that contain information about healthcare expenses. 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. Required for [Level 3 and CEDP transactions](https://docs.payroc.com/knowledge/card-payments/enhanced-data). freightAmount: type: integer format: int64 description: > Amount for shipping in the currency's lowest denomination, for example, cents. Required for [Level 3 and CEDP transactions](https://docs.payroc.com/knowledge/card-payments/enhanced-data). 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. Contains parameters required for [Level 3 and CEDP transactions](https://docs.payroc.com/knowledge/card-payments/enhanced-data). required: - subtotal description: > Object that contains information about the breakdown of the transaction. Contains parameters required for [Level 2, Level 3, and CEDP transactions](https://docs.payroc.com/knowledge/card-payments/enhanced-data). title: itemizedBreakdown paymentOrder: type: object properties: orderId: type: string minLength: 1 maxLength: 24 description: Unique identifier that the merchant assigns to the transaction. 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 minLength: 1 maxLength: 256 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 maxLength: 150 description: Address line 1. address2: type: string maxLength: 150 description: Address line 2. address3: type: string maxLength: 150 description: Address line 3. city: type: string maxLength: 50 description: City. state: type: string maxLength: 50 description: Name of the state or state abbreviation. country: type: string minLength: 2 maxLength: 2 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 maxLength: 10 description: Zip code or postal code. description: Object that contains information about the address. title: retrievedAddress retrievedShipping: type: object properties: recipientName: type: string minLength: 0 maxLength: 50 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 maxLength: 50 description: Email address. required: - type - value description: email variant - type: object properties: type: type: string enum: - phone description: 'Discriminator value: phone' value: type: string maxLength: 15 description: Phone number. required: - type - value description: phone variant - type: object properties: type: type: string enum: - mobile description: 'Discriminator value: mobile' value: type: string maxLength: 15 description: Mobile number. required: - type - value description: mobile variant - type: object properties: type: type: string enum: - fax description: 'Discriminator value: fax' value: type: string maxLength: 15 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 minLength: 0 maxLength: 60 description: Customer's first name. lastName: type: string minLength: 0 maxLength: 60 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 minLength: 0 maxLength: 48 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 RetrievedCardEntryMethod: type: string enum: - icc - keyed - swiped - swipedFallback - contactlessIcc - contactlessMsr description: Method that the device used to capture the card details. title: RetrievedCardEntryMethod 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 minLength: 1 maxLength: 200 description: Unique identifier that the merchant assigned to the secure token. customerName: type: string minLength: 1 maxLength: 50 description: Customer's name. token: type: string minLength: 12 maxLength: 19 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 retrievedCard: type: object properties: type: type: string description: Card brand that the card is linked to. For example, Visa. entryMethod: $ref: '#/components/schemas/RetrievedCardEntryMethod' description: Method that the device used to capture the card details. cardholderName: type: string minLength: 1 maxLength: 50 description: Cardholder’s name. cardholderSignature: type: string description: Cardholder’s signature. cardNumber: type: string minLength: 12 maxLength: 19 description: > Masked card number. Our gateway shows only the first six digits and the last four digits of the card number, for example, 500165******0000. expiryDate: type: string pattern: '[0-9]{4}' 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 - cardNumber - expiryDate description: Object that contains the details of the payment card. title: retrievedCard 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 minLength: 10 maxLength: 10 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 minLength: 1 maxLength: 48 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. Our gateway can return any of the following values: - `capture` - [Capture the payment](https://docs.payroc.com/api/schema/card-payments/payments/capture). - `refund` - [Refund the payment](https://docs.payroc.com/api/schema/card-payments/refunds/create-referenced-refund). - `fullyReverse` - [Fully reverse the transaction](https://docs.payroc.com/api/schema/card-payments/refunds/reverse). - `partiallyReverse` - [Partially reverse the payment](https://docs.payroc.com/api/schema/card-payments/refunds/reverse). - `incrementAuthorization` - [Increase the amount of the authorization](https://docs.payroc.com/api/schema/card-payments/payments/adjust). - `adjustTip` - [Adjust the tip post-payment](https://docs.payroc.com/api/schema/card-payments/payments/adjust). - `addSignature` - [Add a signature to the payment](https://docs.payroc.com/api/schema/card-payments/payments/adjust). - `setAsReady` - [Set the transaction’s status to `ready`](https://docs.payroc.com/api/schema/card-payments/payments/adjust). - `setAsPending` - [Set the transaction’s status to `pending`](https://docs.payroc.com/api/schema/card-payments/payments/adjust). 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: > Status of the transaction. The value is one of the following: - `ready` - Successful transaction. We added the payment to the open batch. - `pending` - Successful transaction. We added the payment to the open batch, but we don't collect the funds until the merchant [captures the transaction](https://docs.payroc.com/api/schema/card-payments/payments/capture). - `declined` - Unsuccessful transaction. The cardholder's issuing bank declined the transaction. - `complete` - Successful transaction. The funds have moved to the merchant's bank account. - `referral` - Unsuccessful transaction. The issuing bank identified an issue with the transaction. You should treat a `referral` status as a declined transaction. - `pickup` - Unsuccessful transaction. The issuing bank has reported that the card is lost or stolen. - `reversal` - Transaction cancelled. The transaction was cancelled, and we removed the transaction from the open batch. - `admin` - Transaction under review. We have flagged an issue with the transaction. - `expired` - Transaction expired. If a transaction stays in `pending` status for too long, it expires. - `accepted` - Transaction in progress. The transaction is in progress with the processor but we can't confirm the result yet. 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 TransactionResultHealthcareIndicator: type: string enum: - 'Y' - 'N' - C - R description: > Indicates if we processed the payment as a healthcare expense. The value is one of the following: - `Y` - We processed the payment as a healthcare expense. - `N` - We processed the payment but it didn't contain any healthcare expenses. - `C` - We processed the payment but the card isn't linked to a Flexible Spending Account (FSA) or a Health Savings Account (HSA). - `R` - We processed the payment but the card doesn't support healthcare expenses. title: TransactionResultHealthcareIndicator 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: > Status of the transaction. The value is one of the following: - `ready` - Successful transaction. We added the payment to the open batch. - `pending` - Successful transaction. We added the payment to the open batch, but we don't collect the funds until the merchant [captures the transaction](https://docs.payroc.com/api/schema/card-payments/payments/capture). - `declined` - Unsuccessful transaction. The cardholder's issuing bank declined the transaction. - `complete` - Successful transaction. The funds have moved to the merchant's bank account. - `referral` - Unsuccessful transaction. The issuing bank identified an issue with the transaction. You should treat a `referral` status as a declined transaction. - `pickup` - Unsuccessful transaction. The issuing bank has reported that the card is lost or stolen. - `reversal` - Transaction cancelled. The transaction was cancelled, and we removed the transaction from the open batch. - `admin` - Transaction under review. We have flagged an issue with the transaction. - `expired` - Transaction expired. If a transaction stays in `pending` status for too long, it expires. - `accepted` - Transaction in progress. The transaction is in progress with the processor but we can't confirm the result yet. approvalCode: type: string minLength: 1 maxLength: 48 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 minLength: 1 maxLength: 48 description: Response description from the processor. processorResponseCode: type: string description: Original response code that the processor sent. cardSchemeReferenceId: type: string minLength: 1 maxLength: 64 description: Identifier that the card brand assigns to the payment instruction. healthcareIndicator: $ref: '#/components/schemas/TransactionResultHealthcareIndicator' description: > Indicates if we processed the payment as a healthcare expense. The value is one of the following: - `Y` - We processed the payment as a healthcare expense. - `N` - We processed the payment but it didn't contain any healthcare expenses. - `C` - We processed the payment but the card isn't linked to a Flexible Spending Account (FSA) or a Health Savings Account (HSA). - `R` - We processed the payment but the card doesn't support healthcare expenses. required: - status - responseCode description: Object that contains information about the transaction response details. title: transactionResult customField: type: object properties: name: type: string minLength: 1 maxLength: 56 description: Name of the custom field. value: type: string minLength: 1 maxLength: 100 description: Value for the custom field. required: - name - value title: customField retrievedPayment: type: object properties: paymentId: type: string minLength: 10 maxLength: 10 description: Unique identifier that our gateway assigned to the transaction. processingTerminalId: type: string minLength: 4 maxLength: 50 description: Unique identifier of the terminal that initiated the transaction. operator: type: string minLength: 0 maxLength: 50 description: Operator who initiated the request. order: $ref: '#/components/schemas/paymentOrder' customer: $ref: '#/components/schemas/retrievedCustomer' card: $ref: '#/components/schemas/retrievedCard' 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: retrievedPayment ErrorsItems: type: object properties: message: type: string description: Error message title: ErrorsItems ```### Example request " ```` **`Payment`** ```python Payment import requests url = "https://api.payroc.com/v1/payments/M2MJOG6O2Y" headers = {"Authorization": "Bearer "} response = requests.get(url, headers=headers) print(response.json()) ``` **`Payment`** ```javascript Payment const url = 'https://api.payroc.com/v1/payments/M2MJOG6O2Y'; const options = {method: 'GET', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` **`Payment`** ```go Payment package main import ( "fmt" "net/http" "io" ) func main() { url := "https://api.payroc.com/v1/payments/M2MJOG6O2Y" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("Authorization", "Bearer ") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` **`Payment`** ```ruby Payment require 'uri' require 'net/http' url = URI("https://api.payroc.com/v1/payments/M2MJOG6O2Y") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) request["Authorization"] = 'Bearer ' response = http.request(request) puts response.read_body ``` **`Payment`** ```java Payment import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("https://api.payroc.com/v1/payments/M2MJOG6O2Y") .header("Authorization", "Bearer ") .asString(); ``` **`Payment`** ```php Payment request('GET', 'https://api.payroc.com/v1/payments/M2MJOG6O2Y', [ 'headers' => [ 'Authorization' => 'Bearer ', ], ]); echo $response->getBody(); ``` **`Payment`** ```csharp Payment using RestSharp; var client = new RestClient("https://api.payroc.com/v1/payments/M2MJOG6O2Y"); var request = new RestRequest(Method.GET); request.AddHeader("Authorization", "Bearer "); IRestResponse response = client.Execute(request); ``` **`Payment`** ````swift Payment import Foundation let headers = ["Authorization": "Bearer "] let request = NSMutableURLRequest(url: NSURL(string: "https://api.payroc.com/v1/payments/M2MJOG6O2Y")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "GET" 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 return the details of the payment. Use this method to retrieve information about a card payment. To retrieve a payment, 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. **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. Our gateway returns the following information about the payment: - Order details, including the transaction amount and when it was processed. - Payment card details, including the masked card number, expiry date, and payment method. - Cardholder details, including their contact information and shipping address. - Payment details, including the payment type, status, and response. If the merchant saved the customer's card details, our gateway returns a secureTokenID, which you can use to perform follow-on actions. tags: - 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 minLength: 10 maxLength: 10 responses: '200': description: Successful request. Returns the payment. content: application/json: schema: $ref: '#/components/schemas/retrievedPayment' '400': description: Invalid request 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' '500': description: An error has occured content: application/json: schema: $ref: '#/components/schemas/500' servers: - url: https://api.payroc.com/v1 description: Production - url: https://api.uat.payroc.com/v1 description: UAT 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' '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' 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 minLength: 3 maxLength: 3 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: >- Indicates if this payment is the first payment or if it is a subsequent payment. title: StandingInstructionsSequence StandingInstructionsProcessingModel: type: string enum: - unscheduled - recurring - installment description: > Indicates the type of payment schedule. - '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 minLength: 10 maxLength: 10 description: > Unique identifier of the first payment. **Note:** We recommend that you always send a value for the **paymentId** parameter. cardSchemeReferenceId: type: string minLength: 1 maxLength: 64 description: Identifier that the card brand assigned to the first payment. description: Object that contains information about the first payment. title: firstTxnReferenceData standingInstructions: type: object properties: sequence: $ref: '#/components/schemas/StandingInstructionsSequence' description: >- Indicates if this payment is the first payment or if it is a subsequent payment. processingModel: $ref: '#/components/schemas/StandingInstructionsProcessingModel' description: > Indicates the type of payment schedule. - '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 first payment. required: - sequence - processingModel description: > Object that contains information about repeat payments. Include this object if the payment is part of a recurring billing schedule and you don't use our [subscriptions](https://docs.payroc.com/guides/take-payments/repeat-payments/use-our-gateway) feature. title: standingInstructions 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 exclusiveMinimum: 0 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 maximum: 100 exclusiveMinimum: 0 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 exclusiveMinimum: 0 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 maximum: 100 exclusiveMinimum: 0 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 maximum: 100 exclusiveMinimum: 0 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 exclusiveMinimum: 0 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 HealthcareExpenseType: type: string enum: - copay - clinic - dental - prescription - transit - vision description: Type of healthcare expense. title: HealthcareExpenseType healthcareExpense: type: object properties: type: $ref: '#/components/schemas/HealthcareExpenseType' description: Type of healthcare expense. amount: type: integer format: int64 exclusiveMinimum: 0 description: >- Amount of the healthcare expense. The value is in the currency's lowest denomination, for example, cents. required: - type - amount description: Object that contains information about a healthcare expense. title: healthcareExpense retrievedTax: type: object properties: name: type: string minLength: 1 maxLength: 64 description: Name of the tax. rate: type: number format: double minimum: 0 maximum: 99.99999 description: Tax percentage for the transaction. amount: type: integer format: int64 exclusiveMinimum: 0 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 convenienceFee: type: object properties: amount: type: integer format: int64 exclusiveMinimum: 0 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 lineItem: type: object properties: commodityCode: type: string minLength: 0 maxLength: 45 description: > Commodity code of the item. Required for [Level 3 and CEDP transactions](https://docs.payroc.com/knowledge/card-payments/enhanced-data). productCode: type: string minLength: 0 maxLength: 45 description: > Product code of the item. Required for [Level 3 and CEDP transactions](https://docs.payroc.com/knowledge/card-payments/enhanced-data). description: type: string minLength: 0 maxLength: 250 description: > Description of the item. Required for [Level 3 and CEDP transactions](https://docs.payroc.com/knowledge/card-payments/enhanced-data). unitOfMeasure: $ref: '#/components/schemas/unitOfMeasure' description: > Unit of measurement for the item. Required for [Level 3 and CEDP transactions](https://docs.payroc.com/knowledge/card-payments/enhanced-data). Also required for Level 2 (American Express only). unitPrice: type: integer format: int64 exclusiveMinimum: 0 description: > Price of each unit. Required for [Level 3 and CEDP transactions](https://docs.payroc.com/knowledge/card-payments/enhanced-data). quantity: type: number format: double exclusiveMinimum: 0 description: > Number of units. Required for [Level 3 and CEDP transactions](https://docs.payroc.com/knowledge/card-payments/enhanced-data). discountRate: type: number format: double exclusiveMinimum: 0 description: > Discount rate that the merchant applies to the item. Required for [Level 3 and CEDP transactions](https://docs.payroc.com/knowledge/card-payments/enhanced-data). taxes: type: array items: $ref: '#/components/schemas/retrievedTax' description: > Array of objects that contain information about each tax that applies to the item. Required for [Level 3 and CEDP transactions](https://docs.payroc.com/knowledge/card-payments/enhanced-data). required: - unitPrice - quantity description: > List of line items. Contains parameters required for [Level 3 and CEDP transactions](https://docs.payroc.com/knowledge/card-payments/enhanced-data). 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. Required for [Level 2, Level 3, and CEDP transactions](https://docs.payroc.com/knowledge/card-payments/enhanced-data). 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. healthcareExpenses: type: array items: $ref: '#/components/schemas/healthcareExpense' description: >- Array of healthcareExpense objects that contain information about healthcare expenses. 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. Required for [Level 3 and CEDP transactions](https://docs.payroc.com/knowledge/card-payments/enhanced-data). freightAmount: type: integer format: int64 description: > Amount for shipping in the currency's lowest denomination, for example, cents. Required for [Level 3 and CEDP transactions](https://docs.payroc.com/knowledge/card-payments/enhanced-data). 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. Contains parameters required for [Level 3 and CEDP transactions](https://docs.payroc.com/knowledge/card-payments/enhanced-data). required: - subtotal description: > Object that contains information about the breakdown of the transaction. Contains parameters required for [Level 2, Level 3, and CEDP transactions](https://docs.payroc.com/knowledge/card-payments/enhanced-data). title: itemizedBreakdown paymentOrder: type: object properties: orderId: type: string minLength: 1 maxLength: 24 description: Unique identifier that the merchant assigns to the transaction. 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 minLength: 1 maxLength: 256 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 maxLength: 150 description: Address line 1. address2: type: string maxLength: 150 description: Address line 2. address3: type: string maxLength: 150 description: Address line 3. city: type: string maxLength: 50 description: City. state: type: string maxLength: 50 description: Name of the state or state abbreviation. country: type: string minLength: 2 maxLength: 2 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 maxLength: 10 description: Zip code or postal code. description: Object that contains information about the address. title: retrievedAddress retrievedShipping: type: object properties: recipientName: type: string minLength: 0 maxLength: 50 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 maxLength: 50 description: Email address. required: - type - value description: email variant - type: object properties: type: type: string enum: - phone description: 'Discriminator value: phone' value: type: string maxLength: 15 description: Phone number. required: - type - value description: phone variant - type: object properties: type: type: string enum: - mobile description: 'Discriminator value: mobile' value: type: string maxLength: 15 description: Mobile number. required: - type - value description: mobile variant - type: object properties: type: type: string enum: - fax description: 'Discriminator value: fax' value: type: string maxLength: 15 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 minLength: 0 maxLength: 60 description: Customer's first name. lastName: type: string minLength: 0 maxLength: 60 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 minLength: 0 maxLength: 48 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 RetrievedCardEntryMethod: type: string enum: - icc - keyed - swiped - swipedFallback - contactlessIcc - contactlessMsr description: Method that the device used to capture the card details. title: RetrievedCardEntryMethod 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 minLength: 1 maxLength: 200 description: Unique identifier that the merchant assigned to the secure token. customerName: type: string minLength: 1 maxLength: 50 description: Customer's name. token: type: string minLength: 12 maxLength: 19 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 retrievedCard: type: object properties: type: type: string description: Card brand that the card is linked to. For example, Visa. entryMethod: $ref: '#/components/schemas/RetrievedCardEntryMethod' description: Method that the device used to capture the card details. cardholderName: type: string minLength: 1 maxLength: 50 description: Cardholder’s name. cardholderSignature: type: string description: Cardholder’s signature. cardNumber: type: string minLength: 12 maxLength: 19 description: > Masked card number. Our gateway shows only the first six digits and the last four digits of the card number, for example, 500165******0000. expiryDate: type: string pattern: '[0-9]{4}' 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 - cardNumber - expiryDate description: Object that contains the details of the payment card. title: retrievedCard 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 minLength: 10 maxLength: 10 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 minLength: 1 maxLength: 48 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. Our gateway can return any of the following values: - `capture` - [Capture the payment](https://docs.payroc.com/api/schema/card-payments/payments/capture). - `refund` - [Refund the payment](https://docs.payroc.com/api/schema/card-payments/refunds/create-referenced-refund). - `fullyReverse` - [Fully reverse the transaction](https://docs.payroc.com/api/schema/card-payments/refunds/reverse). - `partiallyReverse` - [Partially reverse the payment](https://docs.payroc.com/api/schema/card-payments/refunds/reverse). - `incrementAuthorization` - [Increase the amount of the authorization](https://docs.payroc.com/api/schema/card-payments/payments/adjust). - `adjustTip` - [Adjust the tip post-payment](https://docs.payroc.com/api/schema/card-payments/payments/adjust). - `addSignature` - [Add a signature to the payment](https://docs.payroc.com/api/schema/card-payments/payments/adjust). - `setAsReady` - [Set the transaction’s status to `ready`](https://docs.payroc.com/api/schema/card-payments/payments/adjust). - `setAsPending` - [Set the transaction’s status to `pending`](https://docs.payroc.com/api/schema/card-payments/payments/adjust). 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: > Status of the transaction. The value is one of the following: - `ready` - Successful transaction. We added the payment to the open batch. - `pending` - Successful transaction. We added the payment to the open batch, but we don't collect the funds until the merchant [captures the transaction](https://docs.payroc.com/api/schema/card-payments/payments/capture). - `declined` - Unsuccessful transaction. The cardholder's issuing bank declined the transaction. - `complete` - Successful transaction. The funds have moved to the merchant's bank account. - `referral` - Unsuccessful transaction. The issuing bank identified an issue with the transaction. You should treat a `referral` status as a declined transaction. - `pickup` - Unsuccessful transaction. The issuing bank has reported that the card is lost or stolen. - `reversal` - Transaction cancelled. The transaction was cancelled, and we removed the transaction from the open batch. - `admin` - Transaction under review. We have flagged an issue with the transaction. - `expired` - Transaction expired. If a transaction stays in `pending` status for too long, it expires. - `accepted` - Transaction in progress. The transaction is in progress with the processor but we can't confirm the result yet. 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 TransactionResultHealthcareIndicator: type: string enum: - 'Y' - 'N' - C - R description: > Indicates if we processed the payment as a healthcare expense. The value is one of the following: - `Y` - We processed the payment as a healthcare expense. - `N` - We processed the payment but it didn't contain any healthcare expenses. - `C` - We processed the payment but the card isn't linked to a Flexible Spending Account (FSA) or a Health Savings Account (HSA). - `R` - We processed the payment but the card doesn't support healthcare expenses. title: TransactionResultHealthcareIndicator 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: > Status of the transaction. The value is one of the following: - `ready` - Successful transaction. We added the payment to the open batch. - `pending` - Successful transaction. We added the payment to the open batch, but we don't collect the funds until the merchant [captures the transaction](https://docs.payroc.com/api/schema/card-payments/payments/capture). - `declined` - Unsuccessful transaction. The cardholder's issuing bank declined the transaction. - `complete` - Successful transaction. The funds have moved to the merchant's bank account. - `referral` - Unsuccessful transaction. The issuing bank identified an issue with the transaction. You should treat a `referral` status as a declined transaction. - `pickup` - Unsuccessful transaction. The issuing bank has reported that the card is lost or stolen. - `reversal` - Transaction cancelled. The transaction was cancelled, and we removed the transaction from the open batch. - `admin` - Transaction under review. We have flagged an issue with the transaction. - `expired` - Transaction expired. If a transaction stays in `pending` status for too long, it expires. - `accepted` - Transaction in progress. The transaction is in progress with the processor but we can't confirm the result yet. approvalCode: type: string minLength: 1 maxLength: 48 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 minLength: 1 maxLength: 48 description: Response description from the processor. processorResponseCode: type: string description: Original response code that the processor sent. cardSchemeReferenceId: type: string minLength: 1 maxLength: 64 description: Identifier that the card brand assigns to the payment instruction. healthcareIndicator: $ref: '#/components/schemas/TransactionResultHealthcareIndicator' description: > Indicates if we processed the payment as a healthcare expense. The value is one of the following: - `Y` - We processed the payment as a healthcare expense. - `N` - We processed the payment but it didn't contain any healthcare expenses. - `C` - We processed the payment but the card isn't linked to a Flexible Spending Account (FSA) or a Health Savings Account (HSA). - `R` - We processed the payment but the card doesn't support healthcare expenses. required: - status - responseCode description: Object that contains information about the transaction response details. title: transactionResult customField: type: object properties: name: type: string minLength: 1 maxLength: 56 description: Name of the custom field. value: type: string minLength: 1 maxLength: 100 description: Value for the custom field. required: - name - value title: customField retrievedPayment: type: object properties: paymentId: type: string minLength: 10 maxLength: 10 description: Unique identifier that our gateway assigned to the transaction. processingTerminalId: type: string minLength: 4 maxLength: 50 description: Unique identifier of the terminal that initiated the transaction. operator: type: string minLength: 0 maxLength: 50 description: Operator who initiated the request. order: $ref: '#/components/schemas/paymentOrder' customer: $ref: '#/components/schemas/retrievedCustomer' card: $ref: '#/components/schemas/retrievedCard' 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: retrievedPayment ErrorsItems: type: object properties: message: type: string description: Error message title: ErrorsItems ```### Example response **Note:** You can cancel a payment instruction only if its status is `inProgress`. ### Request parameters To create your request, use the following parameters: Use this method to cancel a payment instruction. You can cancel a payment instruction only if its status is `inProgress`. To retrieve the status of a payment instruction, use our [Retrieve Payment Instruction](https://docs.payroc.com/api/schema/payroc-cloud/payment-instructions/retrieve) method. To cancel a payment instruction, you need its paymentInstructionId. Our gateway returned the paymentInstructionId in the response of the [Submit Payment Instruction](https://docs.payroc.com/api/schema/payroc-cloud/payment-instructions/submit) method. tags: - subpackage_payrocCloud/paymentInstructions parameters: - name: paymentInstructionId in: path description: Unique identifier that we assigned to the payment instruction. required: true schema: type: string minLength: 1 maxLength: 36 responses: '204': description: Successful request. We canceled the payment instruction. content: application/json: schema: type: object properties: {} '400': description: Invalid request 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' '500': description: An error has occured content: application/json: schema: $ref: '#/components/schemas/500' servers: - url: https://api.payroc.com/v1 description: Production - url: https://api.uat.payroc.com/v1 description: UAT 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' '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' ErrorsItems: type: object properties: message: type: string description: Error message title: ErrorsItems 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 ```### Example request Use this method to cancel a payment instruction. You can cancel a payment instruction only if its status is `inProgress`. To retrieve the status of a payment instruction, use our [Retrieve Payment Instruction](https://docs.payroc.com/api/schema/payroc-cloud/payment-instructions/retrieve) method. To cancel a payment instruction, you need its paymentInstructionId. Our gateway returned the paymentInstructionId in the response of the [Submit Payment Instruction](https://docs.payroc.com/api/schema/payroc-cloud/payment-instructions/submit) method. tags: - subpackage_payrocCloud/paymentInstructions parameters: - name: paymentInstructionId in: path description: Unique identifier that we assigned to the payment instruction. required: true schema: type: string minLength: 1 maxLength: 36 responses: '204': description: Successful request. We canceled the payment instruction. content: application/json: schema: type: object properties: {} '400': description: Invalid request 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' '500': description: An error has occured content: application/json: schema: $ref: '#/components/schemas/500' servers: - url: https://api.payroc.com/v1 description: Production - url: https://api.uat.payroc.com/v1 description: UAT 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' '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' ErrorsItems: type: object properties: message: type: string description: Error message title: ErrorsItems 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 ```## Response If your request is successful, we cancel the payment instruction. ````