openapi: 3.1.0 info: version: '1' title: Payroc API description: Api for accessing Payroc services contact: name: Payroc Helpdesk url: https://docs.payroc.com/api email: helpdesk@payroc.com servers: - url: https://api.payroc.com/v1 description: Production - url: https://api.uat.payroc.com/v1 description: UAT security: - bearerAuth: [] tags: - name: Apple Pay session description: An Apple Pay session authenticates the merchant's domain with Apple. After you start an Apple Pay session, you can use the Apple Pay JS API to retrieve the cardholder's encrypted payment details. - name: Attachments description: Upload files as attachments. - name: Bank accounts description: Validate bank account information. - name: Bank transfer payments description: Take bank-transfer payments. - name: Bank transfer refunds description: Return payments to customers' bank accounts. - name: Cards description: Validate card information. - name: Contacts description: Individuals who serve as points of contact for the business. - name: Currency conversion description: Offer dynamic currency conversion to customers. - name: Event Subscriptions description: | Create an event subscription so that we notify you when certain events occur, for example, when we change the status of a processing account. When you subscribe to an event, provide the following information: - **Event type** - The events that we should notify you about. You can subscribe to more than one event within the same request. For a list of events that you can subscribe to, go to [Events](https://docs.payroc.com/knowledge/basic-concepts/events). - **Notification method** - The endpoint that we send a notification to if an event occurs. We send notifications by webhook request. - **Event status** - The status of the event subscription. - **Support email address** - Email address that we contact if we can't deliver notifications.
Use our event subscriptions endpoint to do the following: - [**Create event subscription**](#createEventSubscription) - Subscribe to receive notifications when events occur. - [**Update event subscription**](#updateEventSubscription) - Change the details of an event subscription, for example, to receive notifications for an additional event. - [**Partially update an event subscription**](#patchEventSubscription) - Change values of an existing event subscription. - [**Retrieve an event subscription**](#getEventSubscription) - Retrieve all the information that we stored in an event subscription. - [**List event subscriptions**](#listEventSubscriptions) - Retrieve a list of all event subscriptions associated with the ISV's account. - [**Delete event subscription**](#deleteEventSubscription) - name: Funding accounts description: Financial accounts associated with entities. - name: Funding activity description: Activity associated with a payfac account. - name: Funding instructions description: Instructions on how to split fund between recipients. - name: Funding recipients description: Entities that can receive funding but not take payments - name: Hosted Fields description: Create a Hosted Fields session. - name: Merchant platforms description: | A merchant platform is an entity that represents a business and includes its legal information and all processing accounts.

After you create a merchant platform for a business, you can do the following: - [Create and add an additional processing account to a merchant platform.](#createProcessingAccount) - [Retrieve a merchant platform.](#getMerchantAccounts) - [Retrieve a list of merchant platforms.](#listMerchantPlatforms) - [Retrieve a list of open processing accounts that are linked to a merchant platform.](#listMerchantLocations) For more information about boarding a merchant, go to our [Board a merchant](https://docs.payroc.com/guides/board-merchants/boarding) guide. - name: Owners description: Individuals who own or control the business. - name: Payment instructions description: Submit instructions for initiating payments on physical devices running semi-integrated apps. - name: Payment links description: Create and share payment links. - name: Payment plans description: Create and manage payment plans. - name: Payments description: Take card payments. - name: Pricing intents description: Create and manage pricing intents. - name: Processing accounts description: Create and manage processing accounts. - name: Processing terminals description: Retrieve processing terminals - name: Refund instructions description: Submit instructions for initiating refunds on physical devices running semi-integrated apps. - name: Refunds description: Return payments to customers. - name: Secure tokens description: Save customers' payment details. - name: Settlement description: Settlement information - name: Signature instructions description: Submit instructions for capturing signatures on physical devices running semi-integrated apps. - name: Signatures description: Retrieve signatures. - name: Single use tokens description: Create temporary single-use tokens. - name: Subscriptions description: Subscribe customers to payment plans. - name: Terminal orders description: Place and retrieve terminal orders. paths: /funding-recipients: summary: Create and manage funding recipients. post: tags: - Funding recipients summary: Create funding recipient description: "Use this method to create a funding recipient. \n\nA funding recipient is a business or organization that can receive funds but can't run transactions, for example, a charity. \n\nIn the request, include the following information: \n-\tLegal information, including its tax ID, Doing Business As (DBA) name, and address. \n-\tContact information, including the email address. \n-\tOwners' details, including their contact details. \n-\tFunding account details. \n\nOur gateway returns the recipientId of the funding recipient, which you can use to run follow-on actions. \n" operationId: createFundingRecipient parameters: - name: Idempotency-Key in: header required: true 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). schema: &ref_22 type: string format: uuid examples: &ref_23 example: value: 8e03978e-40d5-43e8-bc93-6894a57f9324 requestBody: content: application/json: schema: required: &ref_557 - address - contactMethods - recipientType - taxId - owners - fundingAccounts - doingBusinessAs type: object title: create funding recipient properties: &ref_558 recipientId: type: integer readOnly: true example: 1 status: type: string readOnly: true enum: - approved - rejected - pending example: approved createdDate: type: string format: date-time example: '2024-07-02T15:30:00Z' readOnly: true lastModifiedDate: type: string format: date-time example: '2024-07-02T15:30:00Z' readOnly: true recipientType: type: string description: Type or legal structure of the funding recipient. example: privateCorporation enum: - privateCorporation - publicCorporation - nonProfit - government - privateLlc - publicLlc - privatePartnership - publicPartnership - soleProprietor taxId: type: string description: Employer identification number (EIN) or Social Security number (SSN). example: '123456789' charityId: type: string description: Government identifier of the charity. doingBusinessAs: type: string description: Trading name of the business or organization. address: type: object description: Polymorphic object that contains address information for a funding recipient. oneOf: - required: &ref_0 - city - country - address1 - postalCode - state type: object title: address description: Object that contains information about the address. properties: &ref_1 address1: type: string description: Address line 1. example: 1 Example Ave. maxLength: 150 address2: type: string description: Address line 2. example: Example Address Line 2 maxLength: 150 address3: type: string description: Address line 3. example: Example Address Line 3 maxLength: 150 city: type: string description: City. example: Chicago maxLength: 50 state: type: string description: Name of the state or state abbreviation. example: Illinois maxLength: 50 country: maxLength: 2 minLength: 2 type: string description: Two-digit country code for the country that the business operates in. The format follows the [ISO-3166-1](https://www.iso.org/iso-3166-country-codes.html) standard. example: US postalCode: type: string description: Zip code or postal code. example: '60056' maxLength: 10 contactMethods: type: array minItems: 1 description: "Array of polymorphic objects, which contain contact information. \n\n**Note:** You must provide an email address.\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" items: discriminator: &ref_2 propertyName: type mapping: email: '#/components/schemas/contactMethodEmail' phone: '#/components/schemas/contactMethodPhone' mobile: '#/components/schemas/contactMethodMobile' fax: '#/components/schemas/contactMethodFax' oneOf: &ref_3 - required: &ref_543 - type - value type: object title: email properties: &ref_544 type: type: string description: Type of contact method. enum: - email value: type: string description: Email address. maxLength: 50 example: jane.doe@example.com - required: &ref_545 - type - value type: object title: phone properties: &ref_546 type: type: string description: Type of contact method. enum: - phone value: type: string description: Phone number. maxLength: 15 example: '2025550164' - required: &ref_547 - type - value type: object title: mobile properties: &ref_548 type: type: string description: Type of contact method. enum: - mobile value: type: string description: Mobile number. maxLength: 15 example: '8445557624' - required: &ref_549 - type - value type: object title: fax properties: &ref_550 type: type: string description: Type of contact method. enum: - fax value: type: string description: Fax number. maxLength: 15 example: '2025550110' example: - type: email value: jane.doe@example.com metadata: type: object additionalProperties: type: string description: '[Metadata](https://docs.payroc.com/api/metadata) object you can use to include custom data with your request.' example: yourCustomField: abc123 owners: minItems: 1 description: Array of owner objects. Each object contains information about an individual who owns or manages the funding recipient. type: array items: type: object title: owner required: &ref_30 - firstName - lastName - dateOfBirth - identifiers - contactMethods - relationship - address properties: &ref_31 ownerId: type: integer description: Unique identifier that we assigned to the owner. readOnly: true example: 4564 firstName: type: string description: Owner's first name. example: Jane maxLength: 50 middleName: type: string description: Owner's middle name. example: Helen maxLength: 50 lastName: type: string description: Owner's last name. example: Doe maxLength: 50 dateOfBirth: type: string format: date description: Owner's date of birth. The format of this value is **YYYY-MM-DD**. example: '1964-03-22' address: required: *ref_0 type: object title: address description: Object that contains information about the address. properties: *ref_1 identifiers: minItems: 1 type: array description: Array of IDs. example: - type: nationalId value: xxxxx4320 items: required: &ref_289 - type - value type: object title: identifier properties: &ref_290 type: type: string description: Type of ID provided to verify identity. enum: - nationalId value: type: string description: Social Security Number (SSN) or Social Insurance Number (SIN). example: xxxxx4320 contactMethods: type: array minItems: 1 maxItems: 4 uniqueItems: true description: "Array of polymorphic objects, which contain contact information. \n\n**Note:** If you are adding information about an owner, you must provide at least an email address. If you are adding information about a contact, you must provide at least a contact number. \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" items: discriminator: *ref_2 oneOf: *ref_3 relationship: description: Object that contains information about the owner's relationship to the business. allOf: - required: &ref_552 - isControlProng type: object title: Owner relationship description: Object that contains information about the owner's relationship to the business. properties: &ref_553 equityPercentage: type: number description: Percentage equity stake that the owner holds in the business. format: percentage example: 48.5 default: 0 title: type: string description: Owner's job title. example: CFO isControlProng: type: boolean description: Indicates if the owner is a control prong. You can identify only one control prong for a business. example: true isAuthorizedSignatory: type: boolean description: Indicates if the owner is an authorized signatory. example: false fundingAccounts: minItems: 1 description: Array of fundingAccount objects that you can use to add funding accounts to the funding recipient. type: array items: required: &ref_20 - nameOnAccount - paymentMethods - type - use type: object title: funding account properties: &ref_21 fundingAccountId: type: integer description: Unique identifier that we assigned to the funding account. readOnly: true example: 123 createdDate: type: string description: Date and time that we received your request to create the funding account in our system. format: date-time example: '2024-07-02T12:00:00.000Z' readOnly: true lastModifiedDate: type: string description: Date and time that the funding account was last modified. format: date-time example: '2024-07-02T12:00:00.000Z' readOnly: true status: type: string description: | Status of the funding account. The value is one of the following: - `approved` - We approved the funding account. - `rejected` - We rejected the funding account. - `pending` - We have not yet approved the funding account. - `hold` - Our Risk team have temporarily placed a hold on the funding account. readOnly: true example: pending enum: - approved - rejected - pending - hold type: type: string description: Type of funding account. enum: - checking - savings - generalLedger example: checking use: type: string description: | Indicates if we send funds or withdraw funds from the account. - `credit` - Send funds to the account. - `debit` - Withdraw funds from the account. - `creditAndDebit` - Send funds and withdraw funds from the account. **Note:** If the funding account is associated with a funding recipient, we accept only a value of `credit`. enum: - credit - debit - creditAndDebit nameOnAccount: type: string description: Name of the account holder. example: Jane Doe paymentMethods: description: Array of paymentMethod objects. uniqueItems: true type: array items: &ref_555 title: payment method discriminator: propertyName: type mapping: ach: '#/components/schemas/PaymentMethodAch' oneOf: - type: object title: ACH payment method properties: &ref_554 type: type: string description: Payment method that we use to send funds to the account. enum: - ach value: required: - accountNumber - routingNumber type: object description: Object that contains information about the funding account. properties: routingNumber: maxLength: 9 minLength: 9 type: string description: Routing number of the funding account. example: '123456789' accountNumber: maxLength: 12 minLength: 9 type: string description: Account number of the funding account. example: '1234567890' example: &ref_556 - type: ach value: routingNumber: '123456789' accountNumber: '1234567890' metadata: type: object additionalProperties: type: string description: '[Metadata](https://docs.payroc.com/api/metadata) object you can use to include custom data with your request.' example: yourCustomField: abc123 links: readOnly: true type: array description: Array of HATEOAS links. items: type: object readOnly: true description: Object that contains HATEOAS links for the resource. properties: &ref_4 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: &ref_5 - href - method - rel example: &ref_6 rel: previous method: get href: examples: createFundingRecipient: summary: Create funding recipient description: Create a new funding recipient with owners and funding accounts. value: &ref_877 recipientType: privateCorporation taxId: 12-3456789 doingBusinessAs: Pizza Doe address: address1: 1 Example Ave. address2: Example Address Line 2 address3: Example Address Line 3 city: Chicago state: Illinois country: US postalCode: '60056' contactMethods: - type: email value: jane.doe@example.com - type: phone value: '2025550164' owners: - firstName: Jane middleName: Helen lastName: Doe dateOfBirth: '1964-03-22' address: address1: 1 Example Ave. city: Chicago state: Illinois country: US postalCode: '60056' identifiers: - type: nationalId value: 000-00-4320 contactMethods: - type: email value: jane.doe@example.com - type: phone value: '2025550164' relationship: equityPercentage: 48.5 title: CFO isControlProng: true isAuthorizedSignatory: false fundingAccounts: - type: checking use: credit nameOnAccount: Jane Doe paymentMethods: - type: ach value: routingNumber: '123456789' accountNumber: '1234567890' metadata: yourCustomField: abc123 responses: '201': description: Successful request. We created the funding recipient. content: application/json: schema: required: &ref_7 - address - contactMethods - recipientType - taxId - owners - fundingAccounts - doingBusinessAs type: object title: funding recipient properties: &ref_8 recipientId: type: integer description: Unique identifier that we assigned to the funding recipient. readOnly: true example: 234 status: type: string description: Indicates if we have approved the funding recipient. readOnly: true enum: - approved - rejected - pending example: approved createdDate: type: string description: Date the funding recipient was created. format: date-time example: '2024-07-02T15:30:00Z' readOnly: true lastModifiedDate: type: string description: Date the funding recipient was last modified. format: date-time example: '2024-07-02T15:30:00Z' readOnly: true recipientType: type: string enum: - privateCorporation - publicCorporation - nonProfit - government - privateLlc - publicLlc - privatePartnership - publicPartnership - soleProprietor example: privateCorporation description: Type or legal structure of the funding recipient. taxId: type: string description: Employer identification number (EIN) or Social Security number (SSN). example: '123456789' charityId: type: string description: Government identifier of the charity. doingBusinessAs: type: string description: Legal name of the business or organization. address: type: object description: Polymorphic object that contains address information for a funding recipient. oneOf: - required: *ref_0 type: object title: address description: Object that contains information about the address. properties: *ref_1 contactMethods: type: array minItems: 1 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" items: discriminator: *ref_2 oneOf: *ref_3 example: - type: email value: jane.doe@example.com metadata: type: object additionalProperties: type: string description: '[Metadata](https://docs.payroc.com/api/metadata) object you can use to include custom data with your request.' example: yourCustomField: abc123 owners: readOnly: true description: Array of owner objects associated with the funding recipient. type: array items: type: object title: owner summary properties: ownerId: type: integer description: Unique identifier of the owner. example: 4564 link: type: object description: Object that contains HATEOAS links for the resource. properties: rel: type: string example: owner description: Indicates the relationship between the current resource and the target resource. href: type: string example: https://api.payroc.com/v1/owners/4564 description: URL of the target resource. method: type: string example: get description: HTTP method that you need to use with the target resource. fundingAccounts: readOnly: true description: Array of fundingAccount objects associated with the funding recipient. type: array items: type: object title: funding account summary properties: fundingAccountId: type: integer description: Unique identifier of the funding account. example: 123 status: type: string description: Status of the funding account. enum: - approved - rejected - pending - hold example: pending link: type: object description: Object that contains HATEOAS links for the resource. properties: rel: type: string example: fundingAccount description: Indicates the relationship between the current resource and the target resource. href: type: string example: https://api.payroc.com/v1/funding-accounts/123 description: URL of the target resource. method: type: string example: get description: HTTP method that you need to use with the target resource. example: - fundingAccountId: 123 status: approved link: rel: fundingAccount href: https://api.payroc.com/v1/funding-accounts/123 method: get - fundingAccountId: 124 status: rejected link: rel: fundingAccount href: https://api.payroc.com/v1/funding-accounts/124 method: get headers: location: description: URI reference to created resource. schema: &ref_24 type: string examples: &ref_25 example: value: '400': description: Validation errors content: application/problem+json: schema: type: object properties: &ref_9 type: type: string description: URI reference identifying the problem type example: https://docs.payroc.com/api/errors#bad-request title: type: string description: Short description of the issue. example: Bad request status: type: integer description: Http status code example: 400 detail: type: string description: Explanation of the problem example: One or more validation errors occurred, see error section for more info errors: type: array items: type: object properties: parameter: type: string description: The parameter or field causing the issues example: start_time detail: type: string description: Short detail of the validation errors example: invalid date message: type: string description: Error message example: Expected time, got '' for start_time required: &ref_10 - type - title - detail - status examples: idempotentKeyMissing: summary: Idempotency key missing description: Idempotency key must be supplied value: &ref_26 type: https://docs.payroc.com/api/errors#idempotency-key-missing title: Idempotency-Key header missing status: 400 detail: An 'Idempotency-Key' must be supplied for this request validationError: summary: Bad Request description: One or more validation errors occurred value: &ref_11 type: https://docs.payroc.com/api/errors#bad-request title: Bad request status: 400 detail: One or more validation errors occurred, see error section for more info errors: - parameter: start_time detail: invalid date message: Expected time, got '' for start_time kycCheckFailed: summary: KYC check failed description: KYC check failed value: &ref_17 type: https://docs.payroc.com/api/errors#kyc-check-failed title: Failed KYC Checks status: 400 detail: Entity has been rejected due to failing KYC checks '401': description: Identity could not be verified content: &ref_12 application/problem+json: schema: type: object properties: &ref_531 type: type: string description: URI reference identifying the problem type example: https://docs.payroc.com/api/errors#not-authorized title: type: string description: Short description of the issue. example: Not Authorized status: type: integer description: Http status code example: 401 detail: type: string description: Explanation of the problem example: You do not have the required permissions to perform this action required: &ref_532 - type - title - status - detail examples: notAuthorized: summary: Not Authorized description: Your identity could not be verified value: &ref_874 type: https://docs.payroc.com/api/errors#not-authorized title: Not Authorized status: 401 detail: Your identity could not be verified '403': description: Do not have permissions to perform this action content: &ref_13 application/problem+json: schema: type: object properties: &ref_533 type: type: string description: URI reference identifying the problem type example: https://docs.payroc.com/api/errors#forbidden title: type: string description: Short description of the issue. example: Forbidden status: type: integer description: Http status code example: 403 detail: type: string description: Explanation of the problem example: You do not have the required permissions to perform this action instance: type: string description: Resource path the action was attempted on example: https://api.payroc.com/v1/example/3 resource: type: string description: Resource the action was attempted on example: exampleResource required: &ref_534 - type - title - status - detail examples: forbidden: summary: Forbidden description: You do not have the required permission value: &ref_875 type: https://docs.payroc.com/api/errors#forbidden title: Forbidden status: 403 detail: You do not have the required permissions to perform this action instance: https://api.payroc.com/v1/exampleResource/3 resource: exampleResource '406': description: Not acceptable content: &ref_19 application/problem+json: schema: type: object properties: &ref_535 type: type: string description: URI reference identifying the problem type example: https://docs.payroc.com/api/errors#not-acceptable title: type: string description: Short description of the issue. example: Not acceptable status: type: integer description: Http status code example: 406 detail: type: string description: Explanation of the problem example: Resource does not support the representation requested. required: &ref_536 - type - title - status - detail examples: notAcceptable: summary: Not acceptable description: Requested representation not supported value: &ref_878 type: https://docs.payroc.com/api/errors#not-acceptable title: Not acceptable status: 406 detail: Resource does not support the representation requested '409': description: Conflict content: application/problem+json: schema: type: object properties: &ref_27 type: type: string description: URI reference identifying the problem type example: https://docs.payroc.com/api/errors#resource-already-exists title: type: string description: Short description of the issue. example: Resource already exists status: type: integer description: Http status code example: 409 detail: type: string description: Explanation of the problem example: The resource you attempted to create already exists instance: type: string description: Resource path to the existing resource example: https://api.payroc.com/v1/example/3 errors: type: array items: type: object properties: parameter: type: string description: The parameter or field causing the issues example: start_time detail: type: string description: Short detail of the validation errors example: invalid date message: type: string description: Error message example: Expected time, got '' for start_time link: type: object readOnly: true description: Object that contains HATEOAS links for the resource. properties: *ref_4 required: *ref_5 example: *ref_6 required: &ref_28 - type - title - status - detail examples: idempotentKeyInUse: summary: Idempotency key in use description: Idempotency key in use value: &ref_29 type: https://docs.payroc.com/api/errors#idempotency-key-in-use title: Idempotency-Key in use status: 409 detail: '''Idempotency-Key'' is already in use against a different request' '500': description: An error has occured content: &ref_14 application/problem+json: schema: type: object properties: &ref_541 type: type: string description: URI reference identifying the problem type example: https://docs.payroc.com/api/errors#api-error title: type: string description: Short description of the issue. example: Api error status: type: integer description: Http status code example: 500 detail: type: string description: Explanation of the problem example: Unable to process your request at this time errors: type: array items: type: object properties: message: type: string description: Error message example: Service offline required: &ref_542 - type - title - status - detail examples: apiError: summary: Api error description: Unable to process your request. value: &ref_876 type: https://docs.payroc.com/api/errors#api-error title: Api error status: 500 detail: We are unable to process your request at this time errors: - message: Service offline get: tags: - Funding recipients summary: List funding recipients description: | Use this method to return a [paginated](https://docs.payroc.com/api/pagination) list of funding recipients linked to your account. Note: If you want to view the details of a specific funding recipient and you have its recipientId, use our [Retrieve Funding Recipient](https://docs.payroc.com/api/schema/funding/funding-recipients/retrieve) method. Our gateway returns the following information about each funding recipient in the list: - Tax ID and Doing Business As (DBA) name. - Address and contact details. - Funding accounts linked to the funding recipient. For each funding recipient, we also return the recipientId, which you can use to perform follow-on actions. operationId: listFundingRecipients parameters: - name: before in: query description: | Return the previous page of results before the value that you specify. You can’t send the before parameter in the same request as the after parameter. schema: &ref_32 type: string examples: &ref_33 example: value: '2571' - name: after in: query description: | Return the next page of results after the value that you specify. You can’t send the after parameter in the same request as the before parameter. schema: &ref_34 type: string examples: &ref_35 example: value: '8516' - name: limit in: query description: Limit the maximum number of results that we return for each page. schema: &ref_36 type: integer default: 10 maximum: 100 examples: &ref_37 example: value: 25 responses: '200': description: Successful request. Returns a paginated list of all funding recipients. content: application/json: schema: type: object title: paginated funding recipients allOf: &ref_551 - type: object description: Contains the pagination properties that you use to navigate through a list of results. properties: &ref_38 limit: type: number description: Maximum number of results that we return for each page. example: 25 count: type: number description: | Number of results we returned on this page. **Note:** This might not be the total number of results that match your query. example: 23 hasMore: type: boolean description: Indicates whether there is another page of results available. example: false links: type: array description: Reference links to navigate to the previous page of results or to the next page of results. example: - rel: previous method: get href: - rel: next method: get href: items: type: object readOnly: true description: Object that contains HATEOAS links for the resource. properties: *ref_4 required: *ref_5 example: *ref_6 - type: object properties: data: type: array description: An array of funding recipients items: required: *ref_7 type: object title: funding recipient properties: *ref_8 examples: paginatedFundingRecipients: summary: Paginated funding recipients. description: Paginated list of funding recipients. value: &ref_873 limit: 10 count: 1 hasMore: false links: - rel: previous method: get href: https://api.payroc.com/v1/funding-recipients?before=234&limit=10 data: - recipientId: 234 status: approved createdDate: '2024-07-02T15:30:00Z' lastModifiedDate: '2024-07-02T15:30:00Z' recipientType: privateCorporation taxId: '123456789' doingBusinessAs: Pizza Doe address: address1: 1 Example Ave. city: Chicago state: Illinois country: US postalCode: '60056' contactMethods: - type: phone value: '2025550164' metadata: yourCustomField: abc123 owners: - ownerId: 4564 link: rel: owner method: get href: https://api.payroc.com/v1/owners/4564 fundingAccounts: - fundingAccountId: 123 status: approved link: rel: fundingAccount method: get href: https://api.payroc.com/v1/funding-accounts/123 - fundingAccountId: 124 status: hold link: rel: fundingAccount method: get href: https://api.payroc.com/v1/funding-accounts/124 noActivity: summary: No records found description: Valid request, but no records match the criteria. value: &ref_55 limit: 10 count: 0 hasMore: false links: [] data: [] '400': description: Invalid request content: &ref_15 application/problem+json: schema: type: object properties: *ref_9 required: *ref_10 examples: badRequest: summary: Bad Request description: One or more validation errors occurred value: *ref_11 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '500': description: An error has occured content: *ref_14 /funding-recipients/{recipientId}: get: tags: - Funding recipients summary: Retrieve funding recipient description: | Use this method to retrieve information about a funding recipient. To retrieve a funding recipient, you need its recipientId. Our gateway returned the recipientId in the response of the [Create Funding Recipient](https://docs.payroc.com/api/schema/funding/funding-recipients/create) method. **Note:** If you don't have the recipientId, use our [List Funding Recipients](https://docs.payroc.com/api/schema/funding/funding-recipients/list) method to search for the funding recipient. Our gateway returns the following information about the funding recipient: - Tax ID and Doing Business As (DBA) name. - Address and contact details. - Funding accounts linked to the funding recipient. operationId: getFundingRecipient parameters: - name: recipientId description: Unique identifier that we assigned to the funding recipient. in: path required: true schema: &ref_16 type: integer example: 234 responses: '200': description: Successful request. Returns the requested funding recipient. content: application/json: schema: required: *ref_7 type: object title: funding recipient properties: *ref_8 examples: fundingRecipient: summary: Funding recipient. description: Funding recipients. value: &ref_879 recipientId: 234 status: approved createdDate: '2024-07-02T15:30:00Z' lastModifiedDate: '2024-07-02T15:30:00Z' recipientType: privateCorporation taxId: '123456789' doingBusinessAs: Pizza Doe address: address1: 1 Example Ave. city: Chicago state: Illinois country: US postalCode: '60056' contactMethods: - type: phone value: '2025550164' metadata: yourCustomField: abc123 owners: - ownerId: 4564 link: rel: owner method: get href: https://api.payroc.com/v1/owners/4564 fundingAccounts: - fundingAccountId: 123 status: approved link: rel: fundingAccount method: get href: https://api.payroc.com/v1/funding-accounts/123 - fundingAccountId: 124 status: hold link: rel: fundingAccount method: get href: https://api.payroc.com/v1/funding-accounts/124 '400': description: Invalid request content: *ref_15 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '404': description: Resource not found content: &ref_18 application/problem+json: schema: type: object properties: &ref_338 type: type: string description: URI reference identifying the problem type example: https://docs.payroc.com/api/errors#not-found title: type: string description: Short description of the issue. example: Not found status: type: integer description: Http status code example: 404 detail: type: string description: Explanation of the problem example: Specified resource was not found resource: type: string description: Resource that was not found example: exampleResource required: &ref_339 - type - title - status - detail examples: notFound: summary: Not found description: Resource could not be found value: &ref_340 type: https://docs.payroc.com/api/errors#not-found title: Not found status: 404 detail: Resource not found resource: (The Type of the Resource) '500': description: An error has occured content: *ref_14 put: tags: - Funding recipients summary: Update funding recipient description: | Use this method to update the details of a funding recipient. If a request contains significant changes, we might need to re-approve the funding recipient. To update a funding recipient, you need it's recipientId. Our gateway returned the recipientId in the response of the [Create Funding Recipient](https://docs.payroc.com/api/schema/funding/funding-recipients/create) method. **Note**: If you don't have the recipientId, use our [List Funding Recipients](https://docs.payroc.com/api/schema/funding/funding-recipients/list) method to search for the funding recipient. You can update the following details of a funding recipient: - Doing Business As (DBA) name - Tax ID and charity ID - Address and contact methods operationId: updateFundingRecipient parameters: - name: recipientId description: Unique identifier that we assigned to the funding recipient. in: path required: true schema: *ref_16 example: 234 requestBody: content: application/json: schema: required: *ref_7 type: object title: funding recipient properties: *ref_8 examples: updateFundingRecipient: summary: Update funding recipient description: Update the details of a funding recipient. value: &ref_880 recipientType: privateCorporation taxId: 12-3456789 doingBusinessAs: Doe Hot Dogs address: address1: 2 Example Ave. address2: Example Address Line 2 address3: Example Address Line 3 city: Chicago state: Illinois country: US postalCode: '60056' contactMethods: - type: email value: fred.nerk@example.com - type: phone value: '2025550110' owners: - ownerId: 12346 link: rel: owner href: https://api.payroc.com/v1/owners/12346 method: get fundingAccounts: - fundingAccountId: 124 status: approved link: rel: fundingAccount href: https://api.payroc.com/v1/funding-accounts/124 method: get metadata: responsiblePerson: Jane Doe responses: '204': description: Successful request. We updated the funding recipient. '400': description: Validation errors content: application/problem+json: schema: type: object properties: *ref_9 required: *ref_10 examples: validationError: summary: Bad Request description: One or more validation errors occurred value: *ref_11 kycCheckFailed: summary: KYC check failed description: KYC check failed value: *ref_17 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '404': description: Resource not found content: *ref_18 '406': description: Not acceptable content: *ref_19 '500': description: An error has occured content: *ref_14 delete: tags: - Funding recipients summary: Delete funding recipient description: | Use this method to delete a funding recipient, including its funding accounts and owners. To delete a funding recipient, you need its recipientId. Our gateway returned the recipientId in the response of the [Create Funding Recipient](https://docs.payroc.com/api/schema/funding/funding-recipients/create) method. **Note**: If you don't have the recipientId, use our [List Funding Recipients](https://docs.payroc.com/api/schema/funding/funding-recipients/list) method to search for the funding recipient. operationId: deleteFundingRecipient parameters: - name: recipientId description: Unique identifier that we assigned to the funding recipient. in: path required: true schema: *ref_16 example: 234 responses: '204': description: Successful request. We deleted the funding recipient. '400': description: Invalid request content: *ref_15 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '404': description: Resource not found content: *ref_18 '500': description: An error has occured content: *ref_14 /funding-recipients/{recipientId}/funding-accounts: get: tags: - Funding recipients summary: List funding recipient's funding accounts description: "Use this method to return a list of funding accounts associated with a funding recipient. \n\n**Note:** If you want to view the details of a specific funding account and you have its fundingAccountId, use our [Retrieve Funding Account](https://docs.payroc.com/api/schema/funding/funding-accounts/retrieve) method. \n\nTo retrieve the funding accounts associated with a funding recipient, you need the recipientId. If you don't have the recipientId, use our [List Funding Recipients](https://docs.payroc.com/api/schema/funding/funding-recipients/list) method to search for the funding recipient. \n \nOur gateway returns the following information about each funding account: \n-\tName of the account holder. \n-\tACH details for the account. \n-\tStatus of the account. \n\nOur gateway also returns the fundingAccountId, which you can use to run follow-on actions.\n" operationId: listFundRecipientFundingAccounts parameters: - name: recipientId description: Unique identifier that we assigned to the funding recipient. in: path required: true schema: *ref_16 example: 234 responses: '200': description: Successful request. Returns a list of all funding accounts associated with the funding recipient. content: application/json: schema: type: array items: required: *ref_20 type: object title: funding account properties: *ref_21 examples: fundingAccounts: summary: List of funding accounts description: List of funding accounts. value: &ref_881 - fundingAccountId: 123 createdDate: '2024-07-02T15:30:00Z' lastModifiedDate: '2024-07-02T15:30:00Z' status: approved type: checking use: credit nameOnAccount: Jane Doe paymentMethods: - type: ach value: routingNumber: '*****6789' accountNumber: '******7890' metadata: yourCustomField: abc123 links: - rel: parent href: https://api.payroc.com/v1/funding-recipients/234 method: get - fundingAccountId: 124 createdDate: '2024-07-02T15:30:00Z' lastModifiedDate: '2024-07-02T15:30:00Z' status: pending type: checking use: debit nameOnAccount: Jane Doe paymentMethods: - type: ach value: routingNumber: '*****8725' accountNumber: '******3491' metadata: yourCustomField: abc123 links: - rel: parent href: https://api.payroc.com/v1/funding-recipients/235 method: get '400': description: Invalid request content: *ref_15 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '404': description: Resource not found content: *ref_18 '500': description: An error has occured content: *ref_14 post: tags: - Funding recipients summary: Create funding account description: "Use this method to create a funding account and add it to a funding recipient. \n\nTo add a funding account to a funding recipient, you need the recipientId. Our gateway returned the recipientId in the response of the [Create Funding Recipient](https://docs.payroc.com/api/schema/funding/funding-recipients/create) method. \n\n**Note:** If you don't have the recipientId, use our [List Funding Recipients](https://docs.payroc.com/api/schema/funding/funding-recipients/list) method to search for the funding recipient. \n\nIn the request, include the following information: \n-\tAccount type, for example, if the account is a checking or savings account. \n-\tAccount holder's name. \n-\tACH information, including the routing number and account number of the account. \n\nOur gateway returns the fundingAccountId, which you can use to run follow-on actions.\n" operationId: createFundRecipientFundingAccount parameters: - name: recipientId description: Unique identifier that we assigned to the funding recipient. in: path required: true schema: *ref_16 example: 234 - name: Idempotency-Key in: header required: true 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). schema: *ref_22 examples: *ref_23 requestBody: content: application/json: schema: required: *ref_20 type: object title: funding account properties: *ref_21 examples: createFundingAccount: summary: Create funding account description: Create a funding account and add it to a funding recipient. value: &ref_882 type: savings use: credit nameOnAccount: Fred Nerk paymentMethods: - type: ach value: routingNumber: '123123123' accountNumber: '987654321' metadata: responsiblePerson: Jane Doe responses: '201': description: Successful request. We created the funding account and added it to the funding recipient. content: application/json: schema: required: *ref_20 type: object title: funding account properties: *ref_21 examples: fundingAccount: summary: Funding account description: Funding accounts. value: &ref_883 fundingAccountId: 123 createdDate: '2024-07-02T15:30:00Z' lastModifiedDate: '2024-07-02T15:30:00Z' status: approved type: checking use: credit nameOnAccount: Jane Doe paymentMethods: - type: ach value: routingNumber: '*****6789' accountNumber: '******7890' metadata: yourCustomField: abc123 links: - rel: parent href: https://api.payroc.com/v1/funding-recipients/234 method: get headers: location: description: URI reference to created resource. schema: *ref_24 examples: *ref_25 '400': description: Validation errors content: application/problem+json: schema: type: object properties: *ref_9 required: *ref_10 examples: idempotentKeyMissing: summary: Idempotency key missing description: Idempotency key must be supplied value: *ref_26 validationError: summary: Bad Request description: One or more validation errors occurred value: *ref_11 kycCheckFailed: summary: KYC check failed description: KYC check failed value: *ref_17 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '404': description: Resource not found content: *ref_18 '406': description: Not acceptable content: *ref_19 '409': description: Conflict content: application/problem+json: schema: type: object properties: *ref_27 required: *ref_28 examples: idempotentKeyInUse: summary: Idempotency key in use description: Idempotency key in use value: *ref_29 '500': description: An error has occured content: *ref_14 /funding-recipients/{recipientId}/owners: get: tags: - Funding recipients summary: List funding recipient owners description: "Use this method to return a list of owners of a funding recipient. \n\n**Note:** If you want to view the details of a specific owner and you have their ownerId, use our [Retrieve Owner](https://docs.payroc.com/api/schema/boarding/owners/retrieve) method. \n\nTo list the owners of a funding recipient, you need its recipientId. Our gateway returned the recipientId in the response of the [Create Funding Recipient](https://docs.payroc.com/api/schema/funding/funding-recipients/create) method. If you don't have the recipientId, use our [List Funding Recipients](https://docs.payroc.com/api/schema/funding/funding-recipients/list) method to search for the funding recipient. \n\nOur gateway returns the following information about each owner in the list: \n-\tName, date of birth, and address. \n-\tContact details, including their email address. \n-\tRelationship to the funding recipient. \n\nOur gateway also returns the ownerId, which you can use to perform follow-on actions. \n" operationId: listFundRecipientOwners parameters: - name: recipientId description: Unique identifier that we assigned to the funding recipient. in: path required: true schema: *ref_16 example: 234 responses: '200': description: Successful request. Returns a list of all owners associated with the funding recipient. content: application/json: schema: type: array items: type: object title: owner required: *ref_30 properties: *ref_31 '400': description: Invalid request content: *ref_15 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '404': description: Resource not found content: *ref_18 '500': description: An error has occured content: *ref_14 post: tags: - Funding recipients summary: Create funding recipient owner description: | Use this method to add an additional owner to a funding recipient. To add an owner to a funding recipient, you need the recipientId. Our gateway returned the recipientId in the response of the [Create Funding Recipient](https://docs.payroc.com/api/schema/funding/funding-recipients/create) method. **Note:** If you don't have the recipientId, use our [List Funding Recipients](https://docs.payroc.com/api/schema/funding/funding-recipients/list) method to search for the funding recipient. In the request, include the following information about the owner: - Name, date of birth, and address. - Contact details, including their email address. - Relationship to the funding recipient, including whether they are a control prong. In the response, our gateway returns the ownerId, which you can use to run follow-on actions. operationId: createFundRecipientOwner parameters: - name: recipientId description: Unique identifier that we assigned to the funding recipient. in: path required: true schema: *ref_16 example: 234 - name: Idempotency-Key in: header required: true 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). schema: *ref_22 examples: *ref_23 requestBody: content: application/json: schema: type: object title: owner required: *ref_30 properties: *ref_31 examples: createOwner: summary: Create funding recipient owner description: Add an additional owner to a funding recipient. value: &ref_884 firstName: Fred middleName: Jim lastName: Nerk dateOfBirth: '1980-01-19' address: address1: 2 Example Ave. city: Chicago state: Illinois country: US postalCode: '60056' identifiers: - type: nationalId value: 000-00-9876 contactMethods: - type: email value: fred.nerk@example.com - type: phone value: '2025550110' relationship: equityPercentage: 51.5 title: CEO isControlProng: false isAuthorizedSignatory: true responses: '201': description: Successful request. We created the owner and added it to the funding recipient. content: application/json: schema: type: object title: owner required: *ref_30 properties: *ref_31 headers: location: description: URI reference to created resource. schema: *ref_24 examples: *ref_25 '400': description: Validation errors content: application/problem+json: schema: type: object properties: *ref_9 required: *ref_10 examples: idempotentKeyMissing: summary: Idempotency key missing description: Idempotency key must be supplied value: *ref_26 validationError: summary: Bad Request description: One or more validation errors occurred value: *ref_11 kycCheckFailed: summary: KYC check failed description: KYC check failed value: *ref_17 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '404': description: Resource not found content: *ref_18 '406': description: Not acceptable content: *ref_19 '409': description: Conflict content: application/problem+json: schema: type: object properties: *ref_27 required: *ref_28 examples: idempotentKeyInUse: summary: Idempotency key in use description: Idempotency key in use value: *ref_29 '500': description: An error has occured content: *ref_14 /funding-accounts: get: tags: - Funding accounts summary: List funding accounts description: | Use this method to return a [paginated](https://docs.payroc.com/api/pagination) list of funding accounts associated with your account. **Note:** If you want to view the details of a specific funding account and you have its fundingAccountId, use our [Retrieve Funding Account](https://docs.payroc.com/api/schema/funding/funding-accounts/retrieve) method. Our gateway returns the following information about each funding account in the list: - Name of the account holder and ACH details for the account. - Status of the account. - Whether we send funds to the account, withdraw funds from the account, or both. For each funding account, we also return the fundingAccountId, which you can use to perform follow-on actions. operationId: listFundingAccount parameters: - name: before in: query description: | Return the previous page of results before the value that you specify. You can’t send the before parameter in the same request as the after parameter. schema: *ref_32 examples: *ref_33 - name: after in: query description: | Return the next page of results after the value that you specify. You can’t send the after parameter in the same request as the before parameter. schema: *ref_34 examples: *ref_35 - name: limit in: query description: Limit the maximum number of results that we return for each page. schema: *ref_36 examples: *ref_37 responses: '200': description: Successful request. Returns a paginated list of all funding accounts. content: application/json: schema: type: object title: paginated funding accounts allOf: &ref_559 - type: object description: Contains the pagination properties that you use to navigate through a list of results. properties: *ref_38 - type: object properties: data: type: array description: Array of fundingAccount objects. items: required: *ref_20 type: object title: funding account properties: *ref_21 required: - data examples: fundingAccountExample: summary: Paginated funding accounts value: &ref_885 limit: 2 count: 2 hasMore: true links: - rel: previous method: get href: https://api.payroc.com/v1/funding-accounts?before=123&limit=2 - rel: next method: get href: https://api.payroc.com/v1/funding-accounts?after=124&limit=2 data: - fundingAccountId: 123 createdDate: '2024-07-02T15:30:00Z' lastModifiedDate: '2024-07-02T15:30:00Z' status: approved type: checking use: credit nameOnAccount: Jane Doe paymentMethods: - type: ach value: routingNumber: '*****6789' accountNumber: '******7890' metadata: yourCustomField: abc123 links: - rel: parent href: https://api.payroc.com/v1/processing-accounts/4525644354 method: get - fundingAccountId: 124 createdDate: '2024-07-02T15:30:00Z' lastModifiedDate: '2024-07-02T15:30:00Z' status: pending type: checking use: debit nameOnAccount: Jane Doe paymentMethods: - type: ach value: routingNumber: '*****8725' accountNumber: '******3491' metadata: yourCustomField: abc123 links: - rel: parent href: https://api.payroc.com/v1/funding-recipients/234 method: get noResults: summary: No results found description: No results found value: &ref_886 limit: 10 count: 0 hasMore: false links: [] data: [] '400': description: Invalid request content: *ref_15 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '404': description: Resource not found content: *ref_18 '500': description: An error has occured content: *ref_14 /funding-accounts/{fundingAccountId}: get: tags: - Funding accounts summary: Retrieve funding account description: | Use this method to retrieve information about a funding account. To retrieve a funding account, you need its fundingAccountId. Our gateway returned the fundingAccountId when you created the funding account. **Note:** If you don't have the fundingAccountId, use our [List Funding Accounts](https://docs.payroc.com/api/schema/funding/funding-accounts/list) method to search for the account. Our gateway returns the following information about the funding account: - Name of the account holder and ACH details for the account. - Status of the account. - Whether we send funds to the account, withdraw funds from the account, or both. operationId: getFundingAccount parameters: - name: fundingAccountId in: path required: true description: Unique identifier of the funding account. schema: &ref_39 type: integer examples: &ref_40 example: value: 123 responses: '200': description: Successful request. Returns the requested funding account. content: application/json: schema: required: *ref_20 type: object title: funding account properties: *ref_21 examples: fundingAccountExample: summary: Masked funding account example. value: &ref_887 fundingAccountId: 123 createdDate: '2024-07-02T15:30:00Z' lastModifiedDate: '2024-07-02T15:30:00Z' status: pending type: checking use: credit nameOnAccount: Jane Doe paymentMethods: - type: ach value: routingNumber: '*****6789' accountNumber: '******7890' metadata: yourCustomField: abc123 links: - rel: parent href: https://api.payroc.com/v1/processing-accounts/4525644354 method: get '400': description: Invalid request content: *ref_15 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '404': description: Resource not found content: *ref_18 '500': description: An error has occured content: *ref_14 put: tags: - Funding accounts summary: Update funding account description: "> **Important:** You can't update the details of a funding account that is associated with a processing account. \n\nUse this method to update the details of a funding account that is associated with a funding recipient. \n\nTo update a funding account, you need its fundingAccountId. Our gateway returned the fundingAccountId when you created the funding account. \n\n**Note:** If you don’t have the fundingAccountId, use our [List Funding Accounts](https://docs.payroc.com/api/schema/funding/funding-accounts/list) method to search for the funding account. \n\nYou can update the following details about the funding account: \n-\tAccount type. \n-\tAccount holder's name. \n-\tACH information for the account. \n" operationId: updateFundingAccount parameters: - name: fundingAccountId in: path required: true description: Unique identifier of the funding account. schema: *ref_39 examples: *ref_40 requestBody: content: application/json: schema: required: *ref_20 type: object title: funding account properties: *ref_21 examples: updateFundingAccount: summary: Update funding account description: Update the details of a funding account associated with a funding recipient. value: &ref_888 type: savings use: credit nameOnAccount: Fred Nerk paymentMethods: - type: ach value: routingNumber: '123123123' accountNumber: '987654321' metadata: responsiblePerson: Jane Doe responses: '204': description: Successful request. We updated the funding account. '400': description: Validation errors content: application/problem+json: schema: type: object properties: *ref_9 required: *ref_10 examples: validationError: summary: Bad Request description: One or more validation errors occurred value: *ref_11 kycCheckFailed: summary: KYC check failed description: KYC check failed value: *ref_17 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '404': description: Resource not found content: *ref_18 '406': description: Not acceptable content: *ref_19 '500': description: An error has occured content: *ref_14 delete: tags: - Funding accounts summary: Delete funding account description: | > **Important:** You can't delete a funding account that is associated with a processing account. Use this method to delete a funding account that is associated with a funding recipient. To delete a funding account, you need its fundingAccountId. Our gateway returned the fundingAccountId when you created the funding account. **Note:** If you don't have the fundingAccountId, use our [List Funding Accounts](https://docs.payroc.com/api/schema/funding/funding-accounts/list) method to search for the funding account. operationId: deleteFundingAccount parameters: - name: fundingAccountId in: path required: true description: Unique identifier of the funding account. schema: *ref_39 examples: *ref_40 responses: '204': description: Successful request. We deleted the funding account. '400': description: Invalid request content: *ref_15 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '404': description: Resource not found content: *ref_18 '500': description: An error has occured content: *ref_14 /owners/{ownerId}: get: tags: - Owners summary: Retrieve owner description: | Use this method to retrieve details about an owner of a processing account or an owner associated with a funding recipient. To retrieve an owner, you need their ownerId. Our gateway returned the ownerId in the response of the [Create Processing Account](https://docs.payroc.com/api/schema/boarding/merchant-platforms/create-processing-account) method or the [Create Funding Recipient Owner](https://docs.payroc.com/api/schema/funding/funding-recipients/create-owner) method. **Note:** If you don't have the ownerId, use the [Retrieve Processing Account](https://docs.payroc.com/api/schema/boarding/processing-accounts/retrieve) method if you are searching for a processing account owner, or use the [List Funding Recipient Owners](https://docs.payroc.com/api/schema/funding/funding-recipients/list-owners) method if you are searching for a funding recipient owner. Our gateway returns the following information about an owner: - Name, date of birth, and address. - Contact details, including their email address. - Relationship to the business, including whether they are a control prong or authorized signatory, and their equity stake in the business. operationId: getOwner parameters: - name: ownerId in: path description: Unique identifier that we assigned to the owner. required: true schema: &ref_41 type: integer examples: &ref_42 example: value: 4564 responses: '200': description: Successful request. Returns the requested owner. content: application/json: schema: type: object title: owner required: *ref_30 properties: *ref_31 examples: retrievedOwner: summary: Retrieve owner description: Retrieve a specific owner. value: &ref_889 ownerId: 4564 firstName: Jane middleName: Helen lastName: Doe dateOfBirth: '1964-03-22' address: address1: 1 Example Ave. address2: Example Address Line 2 address3: Example Address Line 3 city: Chicago state: Illinois country: US postalCode: '60056' identifiers: - type: nationalId value: xxxxx4320 contactMethods: - type: email value: jane.doe@example.com relationship: equityPercentage: 48.5 title: CFO isControlProng: true isAuthorizedSignatory: false '400': description: Invalid request content: *ref_15 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '404': description: Resource not found content: *ref_18 '500': description: An error has occured content: *ref_14 put: tags: - Owners summary: Update owner description: | > **Important:** You can't update the details of an owner of a processing account. Use this method to update the details of an owner associated with a funding recipient. To update an owner, you need their ownerId. Our gateway returned the ownerId in the response of the [Create Funding Recipient](https://docs.payroc.com/api/schema/funding/funding-recipients/create) method and the [Create Funding Recipient Owner](https://docs.payroc.com/api/schema/funding/funding-recipients/create-owner) method. **Note:** If you don't have the ownerId, use the [List Funding Recipient Owners](https://docs.payroc.com/api/schema/funding/funding-recipients/list-owners) method, the [Retrieve Funding Recipient](https://docs.payroc.com/api/schema/funding/funding-recipients/retrieve) method, or the [List Funding Recipients](https://docs.payroc.com/api/schema/funding/funding-recipients/list) method to search for the funding recipient owner. You can update the following details about an owner: - Personal details, including their name, date of birth, and address. - Identification details, including their identification type and number. - Contact details, including their email address. - Relationship to the business, including whether they are a control prong. operationId: updateOwner parameters: - name: ownerId in: path description: Unique identifier that we assigned to the owner. required: true schema: *ref_41 examples: *ref_42 requestBody: content: application/json: schema: type: object title: owner required: *ref_30 properties: *ref_31 examples: updateOwner: summary: Update owner description: Update a specific owner. value: &ref_890 firstName: Jane middleName: Helen lastName: Doe dateOfBirth: '1964-03-22' address: address1: 1 Example Ave. address2: Example Address Line 2 address3: Example Address Line 3 city: Chicago state: Illinois country: US postalCode: '60056' identifiers: - type: nationalId value: 000-00-4320 contactMethods: - type: email value: jane.doe@example.com relationship: equityPercentage: 48.5 title: CFO isControlProng: true isAuthorizedSignatory: false responses: '204': description: Successful request. We updated the owner. '400': description: Validation errors. content: application/problem+json: schema: type: object properties: *ref_9 required: *ref_10 examples: validationError: summary: Bad Request description: One or more validation errors occurred value: *ref_11 kycCheckFailed: summary: KYC check failed description: KYC check failed value: *ref_17 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '404': description: Resource not found content: *ref_18 '406': description: Not acceptable content: *ref_19 '500': description: An error has occured content: *ref_14 delete: tags: - Owners summary: Delete owner description: | > **Important:** You can't delete an owner of a processing account. Use this method to delete an owner associated with a funding recipient. You can delete an owner only if the funding recipient has more than one owner. To delete an owner, you need their ownerId. Our gateway returned the ownerId in the response of the [Create Funding Recipient](https://docs.payroc.com/api/schema/funding/funding-recipients/create) method and the [Create Funding Recipient Owner](https://docs.payroc.com/api/schema/funding/funding-recipients/create-owner) method. **Note:** If you don't have the ownerId, use the [List Funding Recipient Owners](https://docs.payroc.com/api/schema/funding/funding-recipients/list-owners) method, the [Retrieve Funding Recipient](https://docs.payroc.com/api/schema/funding/funding-recipients/retrieve) method, or the [List Funding Recipients](https://docs.payroc.com/api/schema/funding/funding-recipients/list) method to search for the funding recipient owner. operationId: deleteOwner parameters: - name: ownerId in: path description: Unique identifier that we assigned to the owner. required: true schema: *ref_41 examples: *ref_42 responses: '204': description: Successful request. We deleted the owner. '400': description: Invalid request content: *ref_15 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '404': description: Resource not found content: *ref_18 '500': description: An error has occured content: *ref_14 /pricing-intents: summary: Provides capabilities to list and create pricing intents. get: summary: List pricing intents description: | Use this method to return a [paginated](https://docs.payroc.com/api/pagination) list of pricing intents associated with the ISV. **Note:** If you want to view the details of a specific pricing intent and you have its pricingIntentId, use our [Retrieve Pricing Intent](https://docs.payroc.com/api/schema/boarding/pricing-intents/retrieve) method. Our gateway returns the following information about each pricing intent in the list: - Information about the fees, including the base fees, gateway fees, and processor fees. - Status of the pricing intent, including whether we approved the pricing intent. For each pricing intent, we also return its pricingIntentId which you can use to perform follow-on actions. operationId: listPricingIntents tags: - Pricing intents parameters: - name: before in: query description: | Return the previous page of results before the value that you specify. You can’t send the before parameter in the same request as the after parameter. schema: *ref_32 examples: *ref_33 - name: after in: query description: | Return the next page of results after the value that you specify. You can’t send the after parameter in the same request as the before parameter. schema: *ref_34 examples: *ref_35 - name: limit in: query description: Limit the maximum number of results that we return for each page. schema: *ref_36 examples: *ref_37 responses: '200': description: Successful response. Returns a list of pricing intents. content: application/json: schema: type: object title: paginated pricing intents description: Object that contains information about your pricing intents. allOf: &ref_599 - type: object description: Contains the pagination properties that you use to navigate through a list of results. properties: *ref_38 - type: object properties: data: type: array description: Array of pricing intent objects. items: type: object title: pricing intent description: Polymorphic object that contains pricing intent information. oneOf: &ref_56 - type: object title: '5.0' description: Object that contains information about a pricing intent for Merchant Processing Agreement (MPA) 5.0. allOf: &ref_598 - type: object title: base pricing intent description: Object that contains information about the base fees. properties: &ref_560 id: type: string description: Unique identifier of the pricing intent. readOnly: true createdDate: type: string example: '2024-07-02T09:00:00' format: date-time description: Date and time that we received your request to create the pricing intent. We return this value in the [ISO-8601](https://www.iso.org/iso-8601-date-and-time-format.html) format. readOnly: true lastUpdatedDate: type: string example: '2024-07-02T09:00:00' format: date-time description: Date and time that the pricing intent was last modified. We return this value in the [ISO-8601](https://www.iso.org/iso-8601-date-and-time-format.html) format. readOnly: true status: type: string description: | Status of the pricing intent. The value can be one of the following: - `active` - We have approved the pricing intent. - `pendingReview` - We have not yet reviewed the pricing intent. - `rejected` - We have rejected the pricing intent. readOnly: true enum: - active - pendingReview - rejected key: type: string description: Unique identifier that you can assign to the pricing intent for your own records. metadata: type: object additionalProperties: type: string description: '[Metadata](https://docs.payroc.com/api/metadata) object that contains your custom data.' example: yourCustomField: abc123 required: &ref_561 - key - type: object title: US pricing agreement version 5.0 description: Object that contains information about U.S. pricing intents for Merchant Processing Agreement (MPA) 5.0. required: &ref_287 - country - version - base properties: &ref_288 country: type: string description: Two-digit code for the country that the pricing intent applies to. The format follows the [ISO-3166-1](https://www.iso.org/iso-3166-country-codes.html) standard. enum: - US version: type: string description: Version of the MPA. enum: - '5.0' base: type: object title: US base fees description: Object that contains information about U.S. base fees. properties: &ref_315 addressVerification: description: Fee for each address verification request. The value is in the currency's lowest denomination, for example, cents. type: - integer - 'null' example: 5 minimum: 0 annualFee: type: object description: Object that contains information about the annual fee. properties: billInMonth: type: string description: Indicates whether we collect the annual fee in June or December. default: december enum: - june - december example: june amount: description: Annual fee. The value is in the currency's lowest denomination, for example, cents. type: integer minimum: 0 example: 100 required: - amount regulatoryAssistanceProgram: type: - integer - 'null' description: Annual fee for the regulatory assistance program. The value is in the currency's lowest denomination, for example, cents. minimum: 0 example: 15 pciNonCompliance: type: integer description: Fee that we apply each month if you aren't compliant with PCI standards. The value is in the currency's lowest denomination, for example, cents. minimum: 3995 maximum: 10000 default: 7495 example: 7495 merchantAdvantage: type: - integer - 'null' description: Monthly fee for Payroc Advantage. The value is in the currency's lowest denomination, for example, cents. minimum: 0 example: 10 platinumSecurity: description: "Polymorphic object that contains billing details for Platinum Security. \n\nThe value of the billingFrequency field determines which variant you should use: \n-\t`monthly` - We collect the fee for Platinum Security each month.\n-\t`annual` - We collect the fee for Platinum Security each year. \n" type: object discriminator: propertyName: billingFrequency mapping: monthly: '#/components/schemas/baseUsMonthly' annual: '#/components/schemas/baseUsAnnual' oneOf: - type: object title: monthly required: &ref_562 - billingFrequency properties: &ref_563 billingFrequency: type: string description: Indicates whether we bill your account monthly or annually. enum: - monthly amount: readOnly: true description: Fee for Platinum Security. The value is in the currency's lowest denomination, for example, cents. type: integer example: 1295 default: 1295 - type: object title: annual required: &ref_564 - billingFrequency properties: &ref_565 billingFrequency: type: string description: Indicates whether we bill your account monthly or annually. enum: - annual amount: readOnly: true description: Fee for the Platinum Security, this is returned in the lowest unit of currency. For example, cents. type: integer example: 15540 default: 15540 maintenance: type: integer description: Monthly fee for maintenance. The value is in the currency's lowest denomination, for example, cents. minimum: 500 example: 1995 minimum: type: integer description: Monthly fee that we charge when the merchant doesn't meet the minimum fee amount. This monthly fee is in the currency's lowest denomination, for example, cents. minimum: 0 example: 100 voiceAuthorization: type: integer description: Fee for each voice authorization. The value is in the currency's lowest denomination, for example, cents. minimum: 95 maximum: 200 default: 95 example: 95 chargeback: type: integer description: Fee for each chargeback. The value is in the currency's lowest denomination, for example, cents. minimum: 750 maximum: 5000 default: 2500 example: 2500 retrieval: type: integer description: Fee for each retrieval. The value is in the currency's lowest denomination, for example, cents. minimum: 275 maximum: 5000 default: 1500 example: 1500 batch: type: integer description: Fee for each batch. The value is in the currency's lowest denomination, for example, cents. minimum: 0 example: 5 earlyTermination: type: integer description: Fee for early termination. The value is in the currency's lowest denomination, for example, cents. minimum: 19500 maximum: 59500 default: 57500 example: 57500 required: &ref_316 - addressVerification - annualFee - regulatoryAssistanceProgram - merchantAdvantage - batch - maintenance - minimum processor: type: object title: US processor fees description: Object that contains information about U.S. processor fees. properties: card: type: object description: "Polymorphic object that contains fees for card transactions. \n\nThe value of the planType field determines which variant you should use: \n-\t`interchangePlus` - Interchange + pricing\n-\t`interchangePlusPlus` - Interchange pricing with three tiers\n-\t`tiered3` - Three-tiered pricing \n-\t`tiered4` - Four-tiered pricing\n-\t`tiered6` - Six-tiered pricing\n-\t`flatRate` - Flat rate pricing\n-\t`consumerChoice` - ConsumerChoice \n-\t`rewardPayChoice` - RewardPayChoice\n" discriminator: propertyName: planType mapping: interchangePlus: '#/components/schemas/interchangePlus' interchangePlusPlus: '#/components/schemas/interchangePlusPlus' tiered3: '#/components/schemas/tiered3' tiered4: '#/components/schemas/tiered4' tiered6: '#/components/schemas/tiered6' flatRate: '#/components/schemas/flatRate' consumerChoice: '#/components/schemas/consumerChoice' rewardPayChoice: '#/components/schemas/rewardPayChoice' oneOf: - type: object title: Interchange Plus Plan description: Object that contains information about Interchange Plus. properties: &ref_317 planType: type: string description: Type of processing plan. enum: - interchangePlus fees: description: Object that contains information about the fees. type: object properties: mastercardVisaDiscover: description: Object that contains the fees for Mastercard, Visa, and Discover transactions. type: object title: Processor Fee properties: &ref_43 volume: description: Percentage of total transaction amount that the processor charges the merchant. allOf: - description: Percentage value up to 2 decimal places. title: percentage type: number format: double minimum: 0 maximum: 100 example: 1.25 transaction: description: Fee for each transaction. The value is in the currency's lowest denomination, for example, cents. allOf: - type: integer minimum: 0 amex: description: "Polymorphic object that contains fees for American Express transactions. \n\nThe value of the type field determines which variant you should use: \n-\t`optBlue` - Amex OptBlue pricing program.\n-\t`direct` - Amex Direct pricing program.\n" discriminator: propertyName: type mapping: optBlue: '#/components/schemas/interchangePlusAmexOptBlue' direct: '#/components/schemas/interchangePlusAmexDirect' oneOf: - type: object title: optBlue required: &ref_566 - type - volume - transaction properties: &ref_567 type: type: string description: Type of American Express program. enum: - optBlue volume: description: Percentage of the total transaction amount that the processor charges the merchant. allOf: - description: Percentage value up to 2 decimal places. title: percentage type: number format: double minimum: 0 maximum: 100 example: 1.25 transaction: description: Fee for each transaction. The value is in the currency's lowest denomination, for example, cents. allOf: - type: integer minimum: 0 - type: object title: direct required: &ref_568 - type - transaction properties: &ref_569 type: type: string description: Type of American Express program. enum: - direct transaction: description: Fee for each transaction. The value is in the currency's lowest denomination, for example, cents. allOf: - type: integer minimum: 0 pinDebit: type: object description: Object that contains the fees for PIN-debit transactions. required: &ref_44 - additionalDiscount - transaction - monthlyAccess properties: &ref_45 additionalDiscount: description: Percentage of additional discount. allOf: - description: Percentage value up to 2 decimal places. title: percentage type: number format: double minimum: 0 maximum: 100 example: 1.25 transaction: description: Fee for each transaction. The value is in the currency's lowest denomination, for example, cents. allOf: - type: integer minimum: 0 monthlyAccess: description: Monthly access fee for using PIN-debit services. The value is in the currency's lowest denomination, for example, cents. allOf: - type: integer minimum: 0 electronicBenefitsTransfer: type: object description: Object that contains the fees for EBT transactions. required: &ref_46 - transaction properties: &ref_47 transaction: description: Fee for each transaction. The value is in the currency's lowest denomination, for example, cents. allOf: - type: integer minimum: 0 enhancedInterchange: type: object description: Object that contains the fees for enhanced interchange services. required: &ref_48 - enrollment - creditToMerchant properties: &ref_49 enrollment: description: Enrollment fee for the enhanced interchange services. The value is in the currency's lowest denomination, for example, cents. allOf: - type: integer minimum: 0 creditToMerchant: description: Percentage of additional discount. allOf: - description: Percentage value up to 2 decimal places. title: percentage type: number format: double minimum: 0 maximum: 100 example: 1.25 specialityCards: type: object description: Object that contains the fees for speciality cards. required: &ref_50 - transaction properties: &ref_51 transaction: description: Fee for each transaction. The value is in the currency's lowest denomination, for example, cents. allOf: - type: integer minimum: 0 required: - mastercardVisaDiscover required: &ref_318 - planType - fees - type: object title: Interchange Plus Plus description: Object that contains information about Interchange Plus Plus. properties: &ref_574 planType: type: string description: Type of processing plan. enum: - interchangePlusPlus fees: type: object description: Object that contains information about the fees. properties: mastercardVisaDiscover: description: Object that contains the fees for Mastercard, Visa, and Discover transactions. type: object required: &ref_52 - qualifiedRate - midQualRate - nonQualRate properties: &ref_53 qualifiedRate: description: Object that contains the fees for a qualified transaction. type: object title: Processor Fee properties: *ref_43 midQualRate: description: Object that contains the fees for a mid-qualified transaction. type: object title: Processor Fee properties: *ref_43 nonQualRate: description: Object that contains the fees for a non-qualified transaction. type: object title: Processor Fee properties: *ref_43 amex: description: "Polymorphic object that contains fees for American Express transactions. \n\nThe value of the type field determines which variant you should use: \n-\t`optBlue` - Amex OptBlue pricing program.\n-\t`direct` - Amex Direct pricing program.\n" discriminator: propertyName: type mapping: optBlue: '#/components/schemas/interchangePlusPlusAmexOptBlue' direct: '#/components/schemas/interchangePlusPlusAmexDirect' oneOf: - type: object title: optBlue required: &ref_570 - type - qualifiedRate - midQualRate - nonQualRate properties: &ref_571 type: type: string description: Type of American Express program. enum: - optBlue qualifiedRate: description: Object that contains the fees for a qualified transaction. type: object title: Processor Fee properties: *ref_43 midQualRate: description: Object that contains the fees for a mid-qualified transaction. type: object title: Processor Fee properties: *ref_43 nonQualRate: description: Object that contains the fees for a non-qualified transaction. type: object title: Processor Fee properties: *ref_43 - type: object title: direct required: &ref_572 - type - transaction properties: &ref_573 type: type: string description: Type of American Express program. enum: - direct transaction: description: Fee for each transaction. The value is in the currency's lowest denomination, for example, cents. allOf: - type: integer minimum: 0 pinDebit: type: object description: Object that contains the fees for PIN-debit transactions. required: *ref_44 properties: *ref_45 electronicBenefitsTransfer: type: object description: Object that contains the fees for EBT transactions. required: *ref_46 properties: *ref_47 enhancedInterchange: type: object description: Object that contains the fees for enhanced interchange services. required: *ref_48 properties: *ref_49 specialityCards: type: object description: Object that contains the fees for speciality cards. required: *ref_50 properties: *ref_51 required: - mastercardVisaDiscover required: &ref_575 - planType - fees - type: object title: Tiered pricing with three tiers description: Object that contains information about tiered pricing with three tiers. properties: &ref_319 planType: type: string description: Type of processing plan. enum: - tiered3 fees: type: object description: Object that contains information about the fees. properties: mastercardVisaDiscover: description: Object that contains the fees for Mastercard, Visa, and Discover transactions. type: object required: *ref_52 properties: *ref_53 amex: description: "Polymorphic object that contains fees for American Express transactions. \n\nThe value of the type field determines which variant you should use: \n-\t`optBlue` - Amex OptBlue pricing program.\n-\t`direct` - Amex Direct pricing program.\n" discriminator: propertyName: type mapping: optBlue: '#/components/schemas/tiered3AmexOptBlue' direct: '#/components/schemas/tiered3AmexDirect' oneOf: - type: object title: optBlue required: &ref_576 - type - qualifiedRate - midQualRate - nonQualRate properties: &ref_577 type: type: string description: Type of American Express program. enum: - optBlue qualifiedRate: description: Object that contains the fees for a qualified transaction. type: object title: Processor Fee properties: *ref_43 midQualRate: description: Object that contains the fees for a mid-qualified transaction. type: object title: Processor Fee properties: *ref_43 nonQualRate: description: Object that contains the fees for a non-qualified transaction. type: object title: Processor Fee properties: *ref_43 - type: object title: direct required: &ref_578 - type - transaction properties: &ref_579 type: type: string description: Type of American Express program. enum: - direct transaction: description: Fee for each transaction. The value is in the currency's lowest denomination, for example, cents. allOf: - type: integer minimum: 0 pinDebit: type: object description: Object that contains the fees for PIN-debit transactions. required: *ref_44 properties: *ref_45 electronicBenefitsTransfer: type: object description: Object that contains the fees for EBT transactions. required: *ref_46 properties: *ref_47 specialityCards: type: object description: Object that contains the fees for speciality cards. required: *ref_50 properties: *ref_51 required: - mastercardVisaDiscover required: &ref_320 - planType - fees - type: object title: Tiered pricing with four tiers description: Object that contains information about tiered pricing with four tiers. properties: &ref_321 planType: type: string description: Type of processing plan. enum: - tiered4 fees: type: object description: Object that contains information about the fees. properties: mastercardVisaDiscover: description: Object that contains the fees for Mastercard, Visa, and Discover transactions. type: object allOf: &ref_54 - type: object required: *ref_52 properties: *ref_53 - type: object required: - premiumRate properties: premiumRate: description: Object that contains the fees for a premium rate transaction. type: object title: Processor Fee properties: *ref_43 amex: description: "Polymorphic object that contains fees for American Express transactions. \n\nThe value of the type field determines which variant you should use: \n-\t`optBlue` - Amex OptBlue pricing program.\n-\t`direct` - Amex Direct pricing program.\n" discriminator: propertyName: type mapping: optBlue: '#/components/schemas/tiered4AmexOptBlue' direct: '#/components/schemas/tiered4AmexDirect' oneOf: - type: object title: optBlue required: &ref_580 - type - qualifiedRate - midQualRate - nonQualRate properties: &ref_581 type: type: string description: Type of American Express program. enum: - optBlue qualifiedRate: description: Object that contains the fees for a qualified transaction. type: object title: Processor Fee properties: *ref_43 midQualRate: description: Object that contains the fees for a mid-qualified transaction. type: object title: Processor Fee properties: *ref_43 nonQualRate: description: Object that contains the fees for a non-qualified transaction. type: object title: Processor Fee properties: *ref_43 - type: object title: direct required: &ref_582 - type - transaction properties: &ref_583 type: type: string description: Type of American Express program. enum: - direct transaction: description: Fee for each transaction. The value is in the currency's lowest denomination, for example, cents. allOf: - type: integer minimum: 0 pinDebit: type: object description: Object that contains the fees for PIN-debit transactions. required: *ref_44 properties: *ref_45 electronicBenefitsTransfer: type: object description: Object that contains the fees for EBT transactions. required: *ref_46 properties: *ref_47 specialityCards: type: object description: Object that contains the fees for speciality cards. required: *ref_50 properties: *ref_51 required: - mastercardVisaDiscover required: &ref_322 - planType - fees - type: object title: Tiered pricing with six tiers description: Object that contains information about tiered pricing with six tiers. properties: &ref_323 planType: type: string description: Type of processing plan. enum: - tiered6 fees: type: object description: Object that contains information about the fees. properties: mastercardVisaDiscover: description: Object that contains the fees for Mastercard, Visa, and Discover transactions. type: object allOf: &ref_584 - type: object allOf: *ref_54 - type: object required: - regulatedCheckCard - unregulatedCheckCard properties: regulatedCheckCard: description: Object that contains the fees for a regulated debit-card transaction. type: object title: Processor Fee properties: *ref_43 unregulatedCheckCard: description: Object that contains the fees for an unregulated debit-card transaction. type: object title: Processor Fee properties: *ref_43 amex: description: "Polymorphic object that contains fees for American Express transactions. \n\nThe value of the type field determines which variant you should use: \n-\t`optBlue` - Amex OptBlue pricing program.\n-\t`direct` - Amex Direct pricing program.\n" discriminator: propertyName: type mapping: optBlue: '#/components/schemas/tiered6AmexOptBlue' direct: '#/components/schemas/tiered6AmexDirect' oneOf: - type: object title: optBlue required: &ref_585 - type - qualifiedRate - midQualRate - nonQualRate properties: &ref_586 type: type: string description: Type of American Express program. enum: - optBlue qualifiedRate: description: Object that contains the fees for a qualified transaction. type: object title: Processor Fee properties: *ref_43 midQualRate: description: Object that contains the fees for a mid-qualified transaction. type: object title: Processor Fee properties: *ref_43 nonQualRate: description: Object that contains the fees for a non-qualified transaction. type: object title: Processor Fee properties: *ref_43 - type: object title: direct required: &ref_587 - type - transaction properties: &ref_588 type: type: string description: Type of American Express program. enum: - direct transaction: description: Fee for each transaction. The value is in the currency's lowest denomination, for example, cents. allOf: - type: integer minimum: 0 pinDebit: type: object description: Object that contains the fees for PIN-debit transactions. required: *ref_44 properties: *ref_45 electronicBenefitsTransfer: type: object description: Object that contains the fees for EBT transactions. required: *ref_46 properties: *ref_47 specialityCards: type: object description: Object that contains the fees for speciality cards. required: *ref_50 properties: *ref_51 required: - mastercardVisaDiscover required: &ref_324 - planType - fees - type: object title: Flat Rate Plan description: Object that contains information about Flat Rate. properties: &ref_325 planType: type: string description: Type of processing plan. enum: - flatRate fees: description: Object that contains information about the Flat Rate fees. type: object properties: standardCards: description: Object that contains the fees for standard card transactions. type: object title: Processor Fee properties: *ref_43 amex: description: Polymorphic object that contains fees for American Express transactions. discriminator: propertyName: type mapping: direct: '#/components/schemas/flatRateAmexDirect' oneOf: - type: object title: direct required: &ref_589 - type - transaction properties: &ref_590 type: type: string description: Type of American Express program. enum: - direct transaction: description: Fee for each transaction. The value is in the currency's lowest denomination, for example, cents. allOf: - type: integer minimum: 0 pinDebit: type: object description: Object that contains the fees for PIN-debit transactions. required: *ref_44 properties: *ref_45 electronicBenefitsTransfer: type: object description: Object that contains the fees for EBT transactions. required: *ref_46 properties: *ref_47 specialityCards: type: object description: Object that contains the fees for speciality cards. required: *ref_50 properties: *ref_51 required: - standardCards required: &ref_326 - planType - fees - type: object title: Consumer Choice Plan description: Object that contains information about ConsumerChoice. properties: &ref_327 planType: type: string description: Type of processing plan. enum: - consumerChoice fees: type: object description: Object that contains information about the fees. properties: monthlySubscription: description: Fee for the monthly subscription for the processing plan. The value is in the currency's lowest denomination, for example, cents. allOf: - type: integer minimum: 0 volume: description: Merchant-authorized percentage on non-cash transactions. allOf: - description: Percentage value up to 2 decimal places. title: percentage type: number format: double minimum: 0 maximum: 100 example: 1.25 pinDebit: type: object description: Object that contains the fees for PIN-debit transactions. required: *ref_44 properties: *ref_45 electronicBenefitsTransfer: type: object description: Object that contains the fees for EBT transactions. required: *ref_46 properties: *ref_47 specialityCards: type: object description: Object that contains the fees for speciality cards. required: *ref_50 properties: *ref_51 required: - monthlySubscription - volume required: &ref_328 - planType - fees - type: object title: RewardPayChoice Plan description: Object that contains information about RewardPayChoice. properties: &ref_329 planType: description: Type of processing plan. type: string enum: - rewardPayChoice fees: type: object description: Object that contains information about the fees. properties: monthlySubscription: description: Fee for the monthly subscription for the processing plan. The value is in the currency's lowest denomination, for example, cents. allOf: - type: integer minimum: 0 debit: description: Object that contains information about fees for debit transactions. properties: option: description: Indicates if debit transactions should be charged at interchange plus or flat rate pricing. type: string enum: - interchangePlus - flatRate volume: description: Percentage of the total transaction that the processor charges the merchant. allOf: - description: Percentage value up to 2 decimal places. title: percentage type: number format: double minimum: 0 maximum: 100 example: 1.25 transaction: description: Fee for each transaction. The value is in the currency's lowest denomination, for example, cents. allOf: - type: integer minimum: 0 required: - volume - transaction credit: type: object description: Object that contains information about fees for credit transactions. properties: tips: description: Indicates how the merchant manages tips. type: string enum: - noTips - tipPrompt - tipAdjust cardChargePercentage: description: Percentage of the total transaction amount that the processor charges the cardholder. type: number readOnly: true default: 3 allOf: - description: Percentage value up to 2 decimal places. title: percentage type: number format: double minimum: 0 maximum: 100 example: 1.25 merchantChargePercentage: description: Percentage of the total transaction amount that the processor charges the merchant. type: number readOnly: true default: 0.9 allOf: - description: Percentage value up to 2 decimal places. title: percentage type: number format: double minimum: 0 maximum: 100 example: 1.25 merchantChargePerTransaction: description: Fee for each transaction. The value is in the currency's lowest denomination, for example, cents. allOf: - type: integer minimum: 0 specialityCards: type: object description: Object that contains the fees for speciality cards. required: *ref_50 properties: *ref_51 required: - monthlySubscription - debit - credit required: &ref_330 - planType - fees ach: type: object description: Object that contains the fees for ACH transactions. properties: &ref_331 fees: description: Object that contains processing fees for ACH transactions. type: object properties: transaction: description: Fee for each transaction. The value is in the currency's lowest denomination, for example, cents. type: integer minimum: 0 example: 50 batch: description: Fee for each batch. The value is in the currency's lowest denomination, for example, cents. type: integer minimum: 0 example: 1000 returns: description: Fee for each return. The value is in the currency's lowest denomination, for example, cents. type: integer minimum: 0 example: 400 unauthorizedReturn: description: Fee for each unauthorized return. The value is in the currency's lowest denomination, for example, cents. type: integer minimum: 0 example: 1999 statement: description: Fee for each statement. The value is in the currency's lowest denomination, for example, cents. type: integer minimum: 0 example: 800 monthlyMinimum: description: Minimum monthly value of transactions. The value is in the currency's lowest denomination, for example, cents. type: integer minimum: 0 example: 20000 accountVerification: description: Fee for each account verification. The value is in the currency's lowest denomination, for example, cents. type: integer minimum: 0 example: 100 discountRateUnder10000: description: Percentage discount for ACH transfers less than $10,000. allOf: - description: Percentage value up to 2 decimal places. title: percentage type: number format: double minimum: 0 maximum: 100 example: 1.25 discountRateAbove10000: description: Percentage discount for ACH transfers equal to or more than $10,000. allOf: - description: Percentage value up to 2 decimal places. title: percentage type: number format: double minimum: 0 maximum: 100 example: 1.25 required: - transaction - batch - returns - unauthorizedReturn - statement - monthlyMinimum - accountVerification - discountRateUnder10000 - discountRateAbove10000 gateway: type: object description: Object that contains information about the gateway fees for MPA 5.0. title: gateway fees properties: &ref_591 fees: type: object description: Object that contains information about the gateway fees. properties: monthly: description: Monthly fee for the gateway. The value is in the currency's lowest denomination, for example, cents. allOf: - type: integer minimum: 0 setup: description: Fee for setting up your account with the gateway. The value is in the currency's lowest denomination, for example, cents. allOf: - type: integer minimum: 0 perTransaction: description: Fee for each transaction. The value is in the currency's lowest denomination, for example, cents. allOf: - type: integer minimum: 0 perDeviceMonthly: description: Monthly fee for each device. The value is in the currency's lowest denomination, for example, cents. allOf: - type: integer minimum: 0 required: - monthly - setup - perTransaction - perDeviceMonthly required: &ref_592 - fees services: title: US version 5.0 services array description: Array of polymorphic objects that contain information about additional services that we offer. type: array items: &ref_597 title: hardwareAdvantagePlan type: object description: Object that contains information about the Hardware Advantage Plan. discriminator: &ref_595 propertyName: name mapping: hardwareAdvantagePlan: '#/components/schemas/hardwareAdvantagePlan' oneOf: &ref_596 - type: object description: Object that contains information about the Hardware Advantage Plan. properties: &ref_593 name: type: string description: Name of the service. enum: - hardwareAdvantagePlan example: hardwareAdvantagePlan enabled: description: Indicates if the merchant has signed up for the Hardware Advantage Plan. type: boolean default: true example: true required: &ref_594 - name - enabled uniqueItems: true examples: paginatedResults: summary: Paginated pricing intent description: Example of a paginated pricing intent. value: &ref_891 limit: 1 count: 1 hasMore: true links: - rel: previous method: get href: https://api.payroc.com/v1/pricing-intents?before=5&limit=1 - rel: next method: get href: https://api.payroc.com/v1/pricing-intents?after=5&limit=1 data: - id: '5' createdDate: '2024-07-02T09:00:00' lastUpdatedDate: '2024-07-02T09:00:00' status: pendingReview key: base country: US version: '5.0' base: addressVerification: 5 annualFee: billInMonth: june amount: 100 regulatoryAssistanceProgram: 15 pciNonCompliance: 4995 merchantAdvantage: 10 platinumSecurity: billingFrequency: monthly amount: 1295 maintenance: 500 minimum: 100 voiceAuthorization: 95 chargeback: 2500 retrieval: 1500 batch: 1000 earlyTermination: 57500 processor: card: planType: interchangePlus fees: mastercardVisaDiscover: volume: 1.25 transaction: 5 amex: type: optBlue volume: 1.25 transaction: 10 pinDebit: additionalDiscount: 1.25 transaction: 10 monthlyAccess: 1200 electronicBenefitsTransfer: transaction: 10 enhancedInterchange: enrollment: 1000 creditToMerchant: 5.25 specialityCards: transaction: 10 ach: fees: transaction: 50 batch: 1000 returns: 400 unauthorizedReturn: 1999 statement: 800 monthlyMinimum: 20000 accountVerification: 100 discountRateUnder10000: 5.25 discountRateAbove10000: 10 gateway: fees: monthly: 1000 setup: 25000 perTransaction: 0 perDeviceMonthly: 0 services: - name: hardwareAdvantagePlan enabled: true noActivity: summary: No records found description: Valid request, but no records match the criteria. value: *ref_55 '400': description: Invalid request content: *ref_15 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '500': description: An error has occured content: *ref_14 post: summary: Create pricing intent description: "Use this method to create a pricing intent that you can assign to a processing account. \n\nIn the request, you must provide the following:\n-\tProcessing fees, including the pricing program and the fee to process each transaction.\n-\tGateway fees, including the fee for each transaction handled by our gateway.\n-\tBase fees, including maintenance and PCI fees.\n\nIn the response, our gateway returns information about the pricing intent and the pricingIntentId, which you need for the following methods:\n-\t[Create Merchant Platform](https://docs.payroc.com/api/schema/boarding/merchant-platforms/create) - Assign the pricing intent to a processing account, when you create the merchant platform and its processing accounts.\n-\t[Create Processing Account](https://docs.payroc.com/api/schema/boarding/merchant-platforms/create-processing-account) - Assign the pricing intent to a processing account.\n-\t[Retrieve Pricing Intent](https://docs.payroc.com/api/schema/boarding/pricing-intents/retrieve) - Retrieve information about a pricing intent.\n-\t[Update Pricing Intent](https://docs.payroc.com/api/schema/boarding/pricing-intents/update) - Update the details of a pricing intent. \n-\t[Delete Pricing Intent](https://docs.payroc.com/api/schema/boarding/pricing-intents/delete) - Delete a pricing intent.\n-\t[Partially Update Pricing Intent](https://docs.payroc.com/api/schema/boarding/pricing-intents/partially-update) - Partially update the details of a pricing intent.\n" tags: - Pricing intents operationId: createPricingIntent parameters: - name: Idempotency-Key in: header required: true 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). schema: *ref_22 examples: *ref_23 requestBody: content: application/json: schema: type: object title: pricing intent description: Polymorphic object that contains pricing intent information. oneOf: *ref_56 examples: interchangePlus: summary: Interchange Plus description: Create a pricing intent. value: &ref_892 key: Your-Unique-Identifier metadata: yourCustomField: abc123 country: US version: '5.0' base: addressVerification: 5 annualFee: billInMonth: june amount: 9900 regulatoryAssistanceProgram: 15 pciNonCompliance: 4995 merchantAdvantage: 10 platinumSecurity: billingFrequency: monthly maintenance: 500 minimum: 100 voiceAuthorization: 95 chargeback: 2500 retrieval: 1500 batch: 1500 earlyTermination: 57500 processor: card: planType: interchangePlus fees: mastercardVisaDiscover: volume: 0.12 transaction: 0 amex: type: optBlue volume: 0.12 transaction: 0 services: - name: hardwareAdvantagePlan enabled: true interchangePlusTiered3: summary: Interchange Plus Plus description: Create a pricing intent. value: &ref_893 key: Your-Unique-Identifier metadata: yourCustomField: abc123 country: US version: '5.0' base: addressVerification: 5 annualFee: billInMonth: june amount: 9900 regulatoryAssistanceProgram: 15 pciNonCompliance: 4995 merchantAdvantage: 10 platinumSecurity: billingFrequency: monthly maintenance: 500 minimum: 100 voiceAuthorization: 95 chargeback: 2500 retrieval: 1500 batch: 1500 earlyTermination: 57500 processor: card: planType: interchangePlusPlus fees: mastercardVisaDiscover: qualifiedRate: volume: 0.35 transaction: 10 midQualRate: volume: 0.35 transaction: 10 nonQualRate: volume: 0.35 transaction: 10 amex: type: optBlue qualifiedRate: volume: 0.5 transaction: 10 midQualRate: volume: 0.75 transaction: 10 nonQualRate: volume: 0.75 transaction: 10 pinDebit: additionalDiscount: 1.25 transaction: 10 monthlyAccess: 1200 electronicBenefitsTransfer: transaction: 10 enhancedInterchange: enrollment: 1000 creditToMerchant: 50 specialityCards: transaction: 10 ach: fees: transaction: 50 batch: 5 returns: 400 unauthorizedReturn: 500 statement: 250 monthlyMinimum: 500 accountVerification: 10 discountRateUnder10000: 0.5 discountRateAbove10000: 1 services: - name: hardwareAdvantagePlan enabled: true tiered3: summary: Tiered 3 description: Create a pricing intent. value: &ref_894 key: Your-Unique-Identifier metadata: yourCustomField: abc123 country: US version: '5.0' base: addressVerification: 5 annualFee: billInMonth: june amount: 9900 regulatoryAssistanceProgram: 15 pciNonCompliance: 4995 merchantAdvantage: 10 platinumSecurity: billingFrequency: monthly maintenance: 500 minimum: 100 voiceAuthorization: 95 chargeback: 2500 retrieval: 1500 batch: 1500 earlyTermination: 57500 processor: card: planType: tiered3 fees: mastercardVisaDiscover: qualifiedRate: volume: 1.39 transaction: 0 midQualRate: volume: 1.75 transaction: 0 nonQualRate: volume: 3.84 transaction: 0 amex: type: optBlue qualifiedRate: volume: 1.39 transaction: 0 midQualRate: volume: 1.75 transaction: 0 nonQualRate: volume: 3.84 transaction: 0 ach: fees: transaction: 50 batch: 5 returns: 400 unauthorizedReturn: 500 statement: 250 monthlyMinimum: 500 accountVerification: 10 discountRateUnder10000: 0.5 discountRateAbove10000: 1 gateway: fees: monthly: 2000 setup: 5000 perTransaction: 2000 perDeviceMonthly: 10 services: - name: hardwareAdvantagePlan enabled: true tiered4: summary: Tiered 4 description: Create a pricing intent. value: &ref_895 key: Your-Unique-Identifier metadata: yourCustomField: abc123 country: US version: '5.0' base: addressVerification: 5 annualFee: billInMonth: june amount: 9900 regulatoryAssistanceProgram: 15 pciNonCompliance: 4995 merchantAdvantage: 10 platinumSecurity: billingFrequency: monthly maintenance: 500 minimum: 100 voiceAuthorization: 95 chargeback: 2500 retrieval: 1500 batch: 1500 earlyTermination: 57500 processor: card: planType: tiered4 fees: mastercardVisaDiscover: qualifiedRate: volume: 1.39 transaction: 0 midQualRate: volume: 1.75 transaction: 0 nonQualRate: volume: 3.84 transaction: 0 premiumRate: volume: 3.84 transaction: 0 amex: type: optBlue qualifiedRate: volume: 1.39 transaction: 0 midQualRate: volume: 1.75 transaction: 0 nonQualRate: volume: 3.84 transaction: 0 ach: fees: transaction: 50 batch: 5 returns: 400 unauthorizedReturn: 500 statement: 250 monthlyMinimum: 500 accountVerification: 10 discountRateUnder10000: 0.5 discountRateAbove10000: 1 gateway: fees: monthly: 2000 setup: 5000 perTransaction: 2000 perDeviceMonthly: 10 services: - name: hardwareAdvantagePlan enabled: true tiered6: summary: Tiered 6 description: Create a pricing intent. value: &ref_896 key: Your-Unique-Identifier metadata: yourCustomField: abc123 country: US version: '5.0' base: addressVerification: 5 annualFee: billInMonth: june amount: 9900 regulatoryAssistanceProgram: 15 pciNonCompliance: 4995 merchantAdvantage: 10 platinumSecurity: billingFrequency: monthly maintenance: 500 minimum: 100 voiceAuthorization: 95 chargeback: 2500 retrieval: 1500 batch: 1500 earlyTermination: 57500 processor: card: planType: tiered6 fees: mastercardVisaDiscover: qualifiedRate: volume: 1.39 transaction: 0 midQualRate: volume: 1.75 transaction: 0 nonQualRate: volume: 3.84 transaction: 0 premiumRate: volume: 1.9 transaction: 5 regulatedCheckCard: volume: 1.25 transaction: 5 unregulatedCheckCard: volume: 1.45 transaction: 5 amex: type: optBlue qualifiedRate: volume: 1.39 transaction: 0 midQualRate: volume: 1.75 transaction: 0 nonQualRate: volume: 3.84 transaction: 0 ach: fees: transaction: 50 batch: 5 returns: 400 unauthorizedReturn: 500 statement: 250 monthlyMinimum: 500 accountVerification: 10 discountRateUnder10000: 0.5 discountRateAbove10000: 1 gateway: fees: monthly: 2000 setup: 5000 perTransaction: 2000 perDeviceMonthly: 10 services: - name: hardwareAdvantagePlan enabled: true flatRate: summary: Flat Rate description: Create a pricing intent. value: &ref_897 key: Your-Unique-Identifier metadata: yourCustomField: abc123 country: US version: '5.0' base: addressVerification: 5 annualFee: billInMonth: june amount: 9900 regulatoryAssistanceProgram: 15 pciNonCompliance: 4995 merchantAdvantage: 10 platinumSecurity: billingFrequency: monthly maintenance: 500 minimum: 0 voiceAuthorization: 95 chargeback: 2500 retrieval: 1500 batch: 0 earlyTermination: 57500 processor: card: planType: flatRate fees: standardCards: volume: 2.89 transaction: 25 pinDebit: additionalDiscount: 1.25 transaction: 25 monthlyAccess: 1200 electronicBenefitsTransfer: transaction: 25 specialityCards: transaction: 25 services: - name: hardwareAdvantagePlan enabled: true consumerChoice: summary: Consumer Choice description: Create a pricing intent. value: &ref_898 key: Your-Unique-Identifier metadata: yourCustomField: abc123 country: US version: '5.0' base: addressVerification: 5 annualFee: billInMonth: june amount: 9900 regulatoryAssistanceProgram: 15 pciNonCompliance: 4995 merchantAdvantage: 10 platinumSecurity: billingFrequency: monthly maintenance: 500 minimum: 100 voiceAuthorization: 95 chargeback: 2500 retrieval: 1500 batch: 1500 earlyTermination: 57500 processor: card: planType: consumerChoice fees: monthlySubscription: 2500 volume: 3.5 services: - name: hardwareAdvantagePlan enabled: true rewardPayChoice: summary: Reward Pay Choice description: Create a pricing intent. value: &ref_899 key: Your-Unique-Identifier metadata: yourCustomField: abc123 country: US version: '5.0' base: addressVerification: 5 annualFee: billInMonth: june amount: 9900 regulatoryAssistanceProgram: 15 pciNonCompliance: 4995 merchantAdvantage: 10 platinumSecurity: billingFrequency: monthly maintenance: 500 minimum: 100 voiceAuthorization: 95 chargeback: 2500 retrieval: 1500 batch: 1500 earlyTermination: 57500 processor: card: planType: rewardPayChoice fees: monthlySubscription: 5000 debit: option: interchangePlus volume: 0 transaction: 10 credit: tips: noTips cardChargePercentage: 3 merchantChargePercentage: 0 merchantChargePerTransaction: 10 specialityCards: transaction: 10 services: - name: hardwareAdvantagePlan enabled: true responses: '201': description: Successful response. We created the pricing intent and it is waiting for approval. content: application/json: schema: type: object title: pricing intent description: Polymorphic object that contains pricing intent information. oneOf: *ref_56 examples: createdPricingIntent: summary: Pricing intent description: Pricing intent value: &ref_57 id: '5' createdDate: '2024-07-02T09:00:00' lastUpdatedDate: '2024-07-02T09:00:00' status: pendingReview key: string metadata: yourCustomField: abc123 country: US version: '5.0' base: addressVerification: 5 annualFee: billInMonth: june amount: 100 regulatoryAssistanceProgram: 15 pciNonCompliance: 4995 merchantAdvantage: 10 platinumSecurity: billingFrequency: monthly amount: 1295 maintenance: 500 minimum: 100 voiceAuthorization: 95 chargeback: 2500 retrieval: 1500 batch: 1000 earlyTermination: 57500 processor: card: planType: interchangePlus fees: mastercardVisaDiscover: volume: 1.25 transaction: 5 amex: type: optBlue volume: 1.25 transaction: 10 pinDebit: additionalDiscount: 1.25 transaction: 10 monthlyAccess: 1200 electronicBenefitsTransfer: transaction: 10 enhancedInterchange: enrollment: 1000 creditToMerchant: 5.25 specialityCards: transaction: 10 ach: fees: transaction: 50 batch: 1000 returns: 400 unauthorizedReturn: 1999 statement: 800 monthlyMinimum: 20000 accountVerification: 100 discountRateUnder10000: 5.25 discountRateAbove10000: 10 gateway: fees: monthly: 1000 setup: 25000 perTransaction: 0 perDeviceMonthly: 0 services: - name: hardwareAdvantagePlan enabled: true headers: location: description: URI reference to created resource. schema: *ref_24 examples: *ref_25 '400': description: Validation error content: application/problem+json: schema: type: object properties: *ref_9 required: *ref_10 examples: validationError: summary: Bad Request description: One or more validation errors occurred value: *ref_11 idempotentKeyMissing: summary: Idempotency key missing description: Idempotency key must be supplied value: *ref_26 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '406': description: Not acceptable content: *ref_19 '409': description: Conflict content: application/problem+json: schema: type: object properties: *ref_27 required: *ref_28 examples: idempotentKeyInUse: summary: Idempotency key in use description: Idempotency key in use value: *ref_29 '500': description: An error has occured content: *ref_14 /pricing-intents/{pricingIntentId}: summary: Provides create/read/updated/delete capabilities for specific pricing intents parameters: - in: path name: pricingIntentId required: true description: Unique identifier that we assigned to the pricing intent. schema: &ref_353 type: string examples: &ref_354 example: value: '5' get: summary: Retrieve pricing intent description: | Use this method to retrieve information about a pricing intent. To retrieve a pricing intent, you need its pricingIntentId. Our gateway returned the pricingIntentId in the response of the [Create Pricing Intent](https://docs.payroc.com/api/schema/boarding/pricing-intents/create) method. **Note:** If you don't have the pricingIntentId, use our [List Pricing Intents](https://docs.payroc.com/api/schema/boarding/pricing-intents/list) method to search for the pricing intent. Our gateway returns the following information about the pricing intent: - Information about the fees, including the base fees, gateway fees, and processor fees. - Status of the pricing intent, including whether we approved the pricing intent. operationId: getPricingIntent tags: - Pricing intents responses: '200': description: Successful response. Returns the requested pricing intent. content: application/json: schema: type: object title: pricing intent description: Polymorphic object that contains pricing intent information. oneOf: *ref_56 examples: pricingIntent: summary: Pricing intent description: Pricing intent value: *ref_57 '400': description: Invalid request content: *ref_15 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '404': description: Resource not found content: *ref_18 '500': description: An error has occured content: *ref_14 put: summary: Update pricing intent description: | Use this method to update the details of a pricing intent. If you update a pricing intent, it won't affect merchant that you've previously onboarded. To update a pricing intent, you need its pricingIntentId. Our gateway returned the pricingIntentId in the response of the [Create Pricing Intent](https://docs.payroc.com/api/schema/boarding/pricing-intents/create) method. **Note:** If you don't have the pricingIntentId, use our [List Pricing Intents](https://docs.payroc.com/api/schema/boarding/pricing-intents/list) method to search for the pricing intent. You can update the following details about a pricing intent: - Fees, including the base fees, processor fees, and gateway fees. - Custom name for the pricing intent. - Additional services that merchants can sign up for. operationId: updatePricingIntent tags: - Pricing intents requestBody: content: application/json: schema: type: object title: pricing intent description: Polymorphic object that contains pricing intent information. oneOf: *ref_56 examples: pricingIntent: summary: Create pricing intent description: Create a pricing intent. value: &ref_900 key: Your-Unique-Identifier metadata: yourCustomField: abc123 country: US version: '5.0' base: addressVerification: 5 annualFee: billInMonth: june amount: 9900 regulatoryAssistanceProgram: 15 pciNonCompliance: 4995 merchantAdvantage: 10 platinumSecurity: billingFrequency: monthly maintenance: 500 minimum: 100 voiceAuthorization: 95 chargeback: 2500 retrieval: 1500 batch: 1500 earlyTermination: 57500 processor: card: planType: interchangePlus fees: mastercardVisaDiscover: volume: 1.25 transaction: 5 amex: type: optBlue volume: 1.25 transaction: 5 pinDebit: additionalDiscount: 1.25 transaction: 10 monthlyAccess: 1200 electronicBenefitsTransfer: transaction: 10 enhancedInterchange: enrollment: 1000 creditToMerchant: 5.25 specialityCards: transaction: 10 ach: fees: transaction: 50 batch: 5 returns: 400 unauthorizedReturn: 1999 statement: 800 monthlyMinimum: 20000 accountVerification: 10 discountRateUnder10000: 5.25 discountRateAbove10000: 10 gateway: fees: monthly: 2000 setup: 5000 perTransaction: 2000 perDeviceMonthly: 10 services: - name: hardwareAdvantagePlan enabled: true responses: '204': description: Resource successfully updated '400': description: Invalid request content: *ref_15 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '404': description: Resource not found content: *ref_18 '406': description: Not acceptable content: *ref_19 '500': description: An error has occured content: *ref_14 patch: summary: Partially update pricing intent description: | Use this method to partially update a pricing intent. Structure your request to follow the [RFC 6902](https://datatracker.ietf.org/doc/html/rfc6902) standard. If you update a pricing intent, it won't affect merchants you've previously onboarded. To update a pricing intent, you need its pricingIntentId. Our gateway returned the pricingIntentId in the response of the [Create Pricing Intent](https://docs.payroc.com/api/schema/boarding/pricing-intents/create) method. **Note:** If you don't have the pricingIntentId, use our [List Pricing Intents](https://docs.payroc.com/api/schema/boarding/pricing-intents/list) method to search for the pricing intent. You can update the following details about a pricing intent: - Fees, including the base fees, processor fees, and gateway fees. - Custom name for the pricing intent. - Additional services that merchants can sign up for. operationId: patchPricingIntent tags: - Pricing intents parameters: - name: Idempotency-Key in: header required: true 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). schema: *ref_22 examples: *ref_23 requestBody: content: application/json: schema: type: array description: A JSON Patch document as defined by RFC 6902. items: &ref_101 title: Patch Operation description: A JSON Patch operation as defined by RFC 6902. discriminator: &ref_612 propertyName: op mapping: add: '#/components/schemas/patchAdd' remove: '#/components/schemas/patchRemove' replace: '#/components/schemas/patchReplace' move: '#/components/schemas/patchMove' copy: '#/components/schemas/patchCopy' test: '#/components/schemas/patchTest' oneOf: &ref_613 - type: object title: Patch Add Operation description: A Patch Add Operation. required: &ref_600 - op - path - value properties: &ref_601 op: type: string enum: - add description: '`add` operation.' path: type: string description: | Location where you want to add the value. The format for this value is JSON Pointer. value: description: Value that you want to add to the resource. - type: object title: Patch Remove Operation description: A Patch Remove Operation. required: &ref_602 - op - path properties: &ref_603 op: type: string enum: - remove description: '`remove` operation.' path: type: string description: | Location of the value that you want to remove. The format for this value is JSON Pointer. - type: object title: Patch Replace Operation description: A Patch Replace Operation. required: &ref_604 - op - path - value properties: &ref_605 op: type: string enum: - replace description: '`replace` operation.' path: type: string description: | Location of the value that you want to replace. The format for this value is JSON Pointer. value: description: Value that you want to use as the replacement. - type: object title: Patch Move Operation description: A Patch Move Operation. required: &ref_606 - op - from - path properties: &ref_607 op: type: string enum: - move description: '`move` operation.' from: type: string description: | Location of the value that you want to move. The format for this value is JSON Pointer. path: type: string description: | Location where you want to move the value to. The format for this value is JSON Pointer. - type: object title: Patch Copy Operation description: A Patch Copy Operation. required: &ref_608 - op - from - path properties: &ref_609 op: type: string enum: - copy description: '`copy` operation.' from: type: string description: | Location of the value that you want to copy. The format for this value is JSON Pointer. path: type: string description: | Location where you want to copy the value to. The format for this value is JSON Pointer. - type: object title: Patch Test Operation description: A Patch Test Operation. required: &ref_610 - op - path - value properties: &ref_611 op: type: string enum: - test description: '`test` operation.' path: type: string description: | Location of the value that you want to test. The format for this value is JSON Pointer. value: description: Value that you want to compare with the current value at the path. example: &ref_102 - op: add path: /a/b/c value: - dog - cat - op: remove path: /a/b/c - op: replace path: /a/b/c value: 42 - op: move from: /a/b/c path: /a/b/d - op: copy from: /a/b/d path: /a/b/e - op: test path: /a/b/c value: dog examples: patchPricingIntentRealistic: summary: Partially update pricing intent description: | Partially update an existing pricing intent. Structure your request to follow the RFC 6902 standard. value: &ref_901 - op: replace path: /processor/card/fees/mastercardVisaDiscover/volume value: 1.5 - op: replace path: /gateway/fees/additionalServiceMonthly value: 16 - op: replace path: /base/addressVerification value: 6 patchOperations: summary: Example patch operations that apply the RFC 6902 standard description: | Example patch operations that apply the RFC 6902 standard. value: &ref_103 - op: add path: /a/b/c value: - 123 - 456 - op: remove path: /a/b/c - op: replace path: /a/b/c value: 789 - op: move from: /a/b/c path: /a/b/d - op: copy from: /a/b/d path: /a/b/e - op: test path: /a/b/c value: 123 responses: '200': description: Successful request. We updated the pricing intent. content: application/json: schema: type: object title: pricing intent description: Polymorphic object that contains pricing intent information. oneOf: *ref_56 examples: pricingIntent: summary: Pricing intent description: Pricing intent value: *ref_57 '400': description: Validation error content: application/problem+json: schema: type: object properties: *ref_9 required: *ref_10 examples: validationError: summary: Bad Request description: One or more validation errors occurred value: *ref_11 idempotentKeyMissing: summary: Idempotency key missing description: Idempotency key must be supplied value: *ref_26 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '404': description: Resource not found content: *ref_18 '406': description: Not acceptable content: *ref_19 '409': description: Conflict content: application/problem+json: schema: type: object properties: *ref_27 required: *ref_28 examples: idempotentKeyInUse: summary: Idempotency key in use description: Idempotency key in use value: *ref_29 '500': description: An error has occured content: *ref_14 delete: summary: Delete pricing intent description: | Use this method to delete a pricing intent. > **Important:** When you delete a pricing intent, you can't recover it. You also won't be able to assign the pricing intent to a merchant's boarding application. To delete a pricing intent, you need its pricingIntentId. Our gateway returned the pricingIntentId in the response of the [Create Pricing Intent](https://docs.payroc.com/api/schema/boarding/pricing-intents/create) method. **Note:** If you don't have the pricingIntentId, use our [List Pricing Intents](https://docs.payroc.com/api/schema/boarding/pricing-intents/list) method to search for the pricing intent. operationId: deletePricingIntent tags: - Pricing intents responses: '204': description: Successful request. We deleted the pricing intent. '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '404': description: Resource not found content: *ref_18 '500': description: An error has occured content: *ref_14 /funding-instructions: post: tags: - Funding instructions summary: Create funding instruction description: "Use this method to create a funding instruction that tells us how to distribute the funds from your merchants' transactions. \n\n**Note:** Before you create a funding instruction, you can use our [List Funding Balances](https://docs.payroc.com/api/schema/funding/funding-activity/retrieve-balance) method to view the amount of available funds that a merchant has. \n\nIn your request, include an array of merchantInstruction objects. Each merchantInstruction object contains the following: \n-\tMerchant ID (MID) of the merchant whose funding balance you want to distribute. \n-\tFunding account that you want to send funds to. \n-\tAmount that you want to send to the funding account. \n\nOur gateway returns the instructionId, which you can use to run follow-on actions.\n" operationId: createInstruction parameters: - name: Idempotency-Key in: header required: true 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). schema: *ref_22 examples: *ref_23 requestBody: content: application/json: schema: type: object description: Inform the payfac what to do with the specified funds. ** title: funding instruction properties: &ref_58 instructionId: type: integer description: Unique identifier that we assigned to the funding instruction. example: 64643131 readOnly: true createdDate: type: string description: Date that we created the funding instruction. The date format follows the [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) standard. format: datetime example: '2024-07-02T15:30:00Z' readOnly: true lastModifiedDate: type: string description: Date of the most recent change to the funding instruction. The date format follows the [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) standard. format: datetime example: '2024-07-02T15:30:00Z' readOnly: true status: type: string description: | Status of the funding instruction. Our gateway returns one of the following values: - `accepted` - We have received the funding instruction but have not yet reviewed it. - `pending` - We have received the funding instruction and we are reviewing it. - `completed` - We have reviewed and processed the funding instruction. enum: - accepted - pending - completed readOnly: true example: accepted merchants: type: array description: Array of merchants objects. Each object specifies the merchant whose funding balance we distribute and who you want to send the funds to. items: type: object title: merchant instruction description: Instruction indicating which recipients should receive funding from the specific merchant balance. properties: merchantId: type: string description: Unique identifier that the processor assigned to the merchant. example: '4525644354' recipients: type: array description: Array of recipients objects. Each object contains information about the funding account and the amount of funds we send to the funding account. minItems: 1 items: type: object title: target funding account description: Object that contains information about the target funding account. required: - fundingAccountId - paymentMethod - amount properties: fundingAccountId: type: integer description: Unique identifier that we assigned to the funding account. example: 123 paymentMethod: type: string description: Payment method that we use to send funds to the funding account. enum: - ACH example: ACH amount: type: object description: Object that contains information about the funds that we send to the funding account. required: - value properties: value: type: number description: Amount of funds in the currency's lowest denomination, for example, cents. example: 120000 currency: description: Currency of the value parameter. type: string default: USD enum: - USD example: USD status: readOnly: true type: string description: "Status of the individual payment instruction. Our gateway returns one of the following values: \n-\t`accepted` - We received the payment instruction, but we haven't reviewed it. \n-\t`pending` - We are reviewing the payment instruction. \n-\t`released` - We approved the payment instruction. \n-\t`funded` - We sent the funds to the funding account by ACH. \n-\t`failed` - The ACH payment to the funding account failed. \n-\t`rejected` - We reviewed the payment instruction and rejected it. \n- `onHold` - We have placed the payment instruction on hold. \n" enum: - accepted - pending - released - funded - failed - rejected - onHold example: accepted metadata: type: object additionalProperties: type: string description: '[Metadata](https://docs.payroc.com/api/metadata) object you can use to include custom data with your request.' example: yourCustomField: abc123 link: readOnly: true description: Object that contains HATEOAS links for the resource. type: object properties: rel: description: Indicates the relationship between the current resource and the target resource. type: string example: fundingAccount method: description: HTTP method that you need to use with the target resource. type: string example: get href: description: URL of the target resource. type: string example: https://api.payroc.com/v1/funding-accounts/123 link: readOnly: true description: Object that contains HATEOAS links for the resource. type: object properties: rel: description: Indicates the relationship between the current resource and the target resource. type: string example: merchant method: description: HTTP method that you need to use with the target resource. type: string example: get href: description: URL of the target resource. type: string example: https://api.payroc.com/v1/processing-accounts/4525644354 required: - merchantId - recipients metadata: type: object additionalProperties: type: string description: '[Metadata](https://docs.payroc.com/api/metadata) object you can use to include custom data with your request.' example: yourCustomField: abc123 examples: createFundingInstruction: summary: Funding instruction description: Create a funding instruction to distribute merchant funds to funding accounts. value: &ref_906 merchants: - merchantId: '4525644354' recipients: - fundingAccountId: 123 paymentMethod: ACH amount: value: 120000 currency: USD metadata: yourCustomField: abc123 metadata: yourCustomField: abc123 createFundingInstructionMetadata: summary: Funding instruction with metadata description: Create a funding instruction to distribute merchant funds to funding accounts. value: &ref_907 merchants: - merchantId: '4525644354' recipients: - fundingAccountId: 123 paymentMethod: ACH amount: value: 120000 currency: USD metadata: supplier: IT Support Services metadata: instructionCreatedBy: Jane Doe responses: '201': description: Successful request. We accepted the instructions. content: application/json: schema: type: object description: Inform the payfac what to do with the specified funds. ** title: funding instruction properties: *ref_58 examples: newInstructions: summary: New instruction accepted. value: &ref_908 instructionId: 64643131 createdDate: '2024-07-02T15:30:00Z' lastModifiedDate: '2024-07-02T15:30:00Z' status: accepted merchants: - merchantId: '4525644354' recipients: - status: accepted fundingAccountId: 123 paymentMethod: ACH amount: value: 120000 currency: USD metadata: yourCustomField: abc123 link: rel: fundingAccount method: get href: https://api.payroc.com/v1/funding-accounts/123 link: rel: merchant method: get href: https://api.payroc.com/v1/processing-accounts/4525644354 metadata: instructionRef: abc123 newInstructionAcceptedMetadata: summary: Created funding instruction with metadata value: &ref_909 instructionId: 64643131 createdDate: '2024-07-02T15:30:00Z' lastModifiedDate: '2024-07-02T15:30:00Z' status: accepted merchants: - merchantId: '4525644354' recipients: - status: accepted fundingAccountId: 123 paymentMethod: ACH amount: value: 120000 currency: USD metadata: supplier: IT Support Services link: rel: fundingAccount method: get href: https://api.payroc.com/v1/funding-accounts/123 link: rel: merchant method: get href: https://api.payroc.com/v1/processing-accounts/4525644354 metadata: instructionCreatedBy: Jane Doe headers: location: description: URI reference to created resource. schema: *ref_24 examples: *ref_25 '400': description: Validation error. content: application/problem+json: schema: type: object properties: *ref_9 required: *ref_10 examples: validationError: summary: Bad Request description: One or more validation errors occurred value: *ref_11 insufficientFunds: summary: Insufficient funds description: You do not have enough funds to complete the request. value: &ref_59 type: https://docs.payroc.com/api/errors#insufficient-funds title: Insufficient funds status: 400 detail: You do not have the required funds to complete this transaction idempotentKeyMissing: summary: Idempotency key missing description: Idempotency key must be supplied value: *ref_26 fundingAccountsRestrcited: summary: Funding accounts restricted description: Funding accounts restricted. value: &ref_61 type: https://docs.payroc.com/api/errors#funding-accounts-restricted title: Funding accounts restricted status: 400 detail: One or more funding accounts are restricted and can't receive funding instructions errors: - parameter: fundingAccountId message: Funding account on hold recipientAmountValueLimitExceeded: summary: Recipient amount.value limit exceeded description: One or more recipients exceed the 'amount.value' limit for your account value: &ref_62 type: https://docs.payroc.com/api/errors#recipient-amount-value-limit-exceeded title: Recipient amount.value limit exceeded status: 400 detail: One or more recipients exceed the 'amount.value' limit for your account '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '406': description: Not acceptable content: *ref_19 '409': description: Conflict content: application/problem+json: schema: type: object properties: *ref_27 required: *ref_28 examples: idempotentKeyInUse: summary: Idempotency key in use description: Idempotency key in use value: *ref_29 '500': description: An error has occured content: *ref_14 get: tags: - Funding instructions summary: List funding instructions description: "> Important: You can return a list of funding instructions from only the previous two years. If you want to view a funding instruction from more than two years ago and you have its instructionId, use our [Retrieve Funding Instruction](https://docs.payroc.com/api/schema/funding/funding-instructions/retrieve) method. \n\nUse this method to return a [paginated](https://docs.payroc.com/api/pagination) list of funding instructions within a specific date range. \n\n**Note:** If you want to view the details of a specific funding instruction and you have its instructionId, use our [Retrieve Funding Instruction](https://docs.payroc.com/api/schema/funding/funding-instructions/retrieve) method. \n\nOur gateway returns the following information for each instruction in the list: \n-\tStatus of the funding instruction. \n-\tFunding information, including which merchant's funding balance we distribute and the funding account that we send the balance to. \n\nFor each funding instruction, we also return the instructionId, which you can use to perform follow-on actions. \n" operationId: listInstructions parameters: - name: before in: query description: | Return the previous page of results before the value that you specify. You can’t send the before parameter in the same request as the after parameter. schema: *ref_32 examples: *ref_33 - name: after in: query description: | Return the next page of results after the value that you specify. You can’t send the after parameter in the same request as the before parameter. schema: *ref_34 examples: *ref_35 - name: limit in: query description: Limit the maximum number of results that we return for each page. schema: *ref_36 examples: *ref_37 - name: dateFrom in: query description: Filter by funding instructions sent after a specific date. Send a value in **YYYY-MM-DD** format. required: true schema: &ref_355 type: string format: date examples: &ref_356 example: value: '2024-07-01' - name: dateTo in: query required: true description: Filter by funding instructions sent before a specific date. Send a value in **YYYY-MM-DD** format. schema: &ref_357 type: string format: date examples: &ref_358 example: value: '2024-07-03' responses: '200': description: Successful request. Returns a list of funding instructions. content: application/json: schema: type: object allOf: - type: object description: Contains the pagination properties that you use to navigate through a list of results. properties: *ref_38 - type: object properties: data: type: array description: Array of fundingInstruction objects. items: allOf: - type: object description: Inform the payfac what to do with the specified funds. ** title: funding instruction properties: *ref_58 - type: object properties: link: type: object readOnly: true description: Object that contains HATEOAS links for the resource. properties: *ref_4 required: *ref_5 example: *ref_6 required: - data examples: listSplitsExample: summary: Paginated instructions list value: &ref_902 limit: 2 count: 2 hasMore: true links: - rel: previous method: get href: https://api.payroc.com/v1/funding-instructions?before=64643131&limit=2&datefrom=2024-07-01&dateto=2024-07-03 - rel: next method: get href: https://api.payroc.com/v1/funding-instructions?after=64643132&limit=2&datefrom=2024-07-01&dateto=2024-07-03 data: - instructionId: 64643131 createdDate: '2024-07-02T15:30:00Z' lastModifiedDate: '2024-07-02T15:30:00Z' status: completed merchants: - merchantId: '4525644354' recipients: - status: funded fundingAccountId: 123 paymentMethod: ACH amount: value: 120000 currency: USD metadata: yourCustomField: abc123 link: rel: fundingAccount method: get href: https://api.payroc.com/v1/funding-accounts/123 - status: rejected fundingAccountId: 124 paymentMethod: ACH amount: value: 50050 currency: USD metadata: yourCustomField: abc123 link: rel: fundingAccount method: get href: https://api.payroc.com/v1/funding-accounts/124 link: rel: merchant method: get href: https://api.payroc.com/v1/processing-accounts/4525644354 metadata: yourCustomField: abc123 link: rel: fundingInstruction method: get href: https://api.payroc.com/v1/funding-instructions/64643131 - instructionId: 64643132 createdDate: '2024-07-02T15:30:00Z' lastModifiedDate: '2024-07-02T15:30:00Z' status: accepted merchants: - merchantId: '4525644354' recipients: - status: accepted fundingAccountId: 123 paymentMethod: ACH amount: value: 5000 currency: USD metadata: yourCustomField: abc123 link: rel: fundingAccount method: get href: https://api.payroc.com/v1/funding-accounts/123 link: rel: merchant method: get href: https://api.payroc.com/v1/processing-accounts/4525644354 - merchantId: '4525644354' recipients: - status: accepted fundingAccountId: 124 paymentMethod: ACH amount: value: 1000 currency: USD metadata: yourCustomField: abc123 link: rel: fundingAccount method: get href: https://api.payroc.com/v1/funding-accounts/124 link: rel: merchant method: get href: https://api.payroc.com/v1/processing-accounts/4525644354 metadata: yourCustomField: abc123 link: rel: fundingInstruction method: get href: https://api.payroc.com/v1/funding-instructions/64643132 noActivity: summary: No records found description: Valid request, but no records match the criteria. value: *ref_55 '400': description: Validation error. content: application/problem+json: schema: type: object properties: *ref_9 required: *ref_10 examples: parameterError: summary: Bad request description: One or more validation errors occurred. value: &ref_903 type: https://docs.payroc.com/api/errors#bad-request title: Bad request status: 400 detail: One or more validation errors occurred, see error section for more info errors: - parameter: datefrom detail: invalid date message: Expected date, got \"abc\" paginationError: summary: Bad request description: One or more validation errors occurred value: type: https://docs.payroc.com/api/errors#bad-request title: Bad request status: 400 detail: One or more validation errors occurred, see error section for more info errors: - parameter: before detail: invalid value message: Expected integer, got abc outsideRecordRange: summary: Bad request description: Requested data outside allowed range. value: type: https://docs.payroc.com/api/errors#bad-request title: Bad request status: 400 detail: One or more validation errors occurred, see error section for more info errors: - parameter: datefrom detail: invalid date message: datefrom cannot be longer than two years ago. '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '406': description: Not acceptable content: *ref_19 '500': description: An error has occured content: *ref_14 /funding-instructions/{instructionId}: parameters: - name: instructionId in: path required: true description: Unique identifier that we assigned to the funding instruction. schema: &ref_359 type: integer examples: &ref_360 example: value: 64643131 get: tags: - Funding instructions summary: Retrieve funding instruction operationId: getInstruction description: "Use this method to retrieve information about a funding instruction. \n\nTo retrieve a funding instruction, you need its instructionId. Our gateway returned the instructionId in the response of the [Create Funding Instruction](https://docs.payroc.com/api/schema/funding/funding-instructions/create) method. \n\n**Note:** If you don't have the instructionId, use our [List Funding Instructions](https://docs.payroc.com/api/schema/funding/funding-instructions/list) method to search for the funding instruction. \n\nOur gateway returns the following information about the funding instruction: \n-\tStatus of the funding instruction. \n-\tFunding information, including which merchant's funding balance we distribute and the funding account that we send the balance to. \n" responses: '200': description: Successful request. Returns the funding instruction. content: application/json: schema: type: object description: Inform the payfac what to do with the specified funds. ** title: funding instruction properties: *ref_58 '400': description: Validation error. content: application/problem+json: schema: type: object properties: *ref_9 required: *ref_10 examples: instructionIdError: summary: Bad request description: One or more validation errors occurred. value: &ref_60 type: https://docs.payroc.com/api/errors#bad-request title: Bad request status: 400 detail: One or more validation errors occurred, see error section for more info errors: - parameter: instructionId detail: invalid value message: Expected integer, got abc '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '404': description: Resource not found content: *ref_18 '406': description: Not acceptable content: *ref_19 '500': description: An error has occured content: *ref_14 put: tags: - Funding instructions summary: Update funding instruction operationId: updateInstructions description: "> **Important:** You can update a funding instruction only if its status is `accepted`. To view the status of a funding instruction, use our [Retrieve Funding Instruction](https://docs.payroc.com/api/schema/funding/funding-instructions/retrieve) method. \n\nUse this method to update the details of a funding instruction. \n\nTo update a funding instruction, you need its instructionId. Our gateway returned the instructionId in the response of the [Create Funding Instruction](https://docs.payroc.com/api/schema/funding/funding-instructions/create) method. \n\n**Note:** If you don't have the fundingInstructionId, use our [List Funding Instructions](https://docs.payroc.com/api/schema/funding/funding-instructions/list) method to search for the funding instruction. \n\nYou can modify the following information for the funding instruction: \n-\tMerchant ID (MID) of the merchant whose funding balance you want to distribute. \n-\tFunding account that you want to send funds to. \n-\tAmount that you want to send to the funding account. \n" requestBody: content: application/json: schema: type: object description: Inform the payfac what to do with the specified funds. ** title: funding instruction properties: *ref_58 examples: updateFundingInstruction: summary: Update funding instruction description: Update an existing funding instruction to modify merchant funds distribution. value: &ref_910 merchants: - merchantId: '9876543219' recipients: - fundingAccountId: 124 paymentMethod: ACH amount: value: 69950 currency: USD metadata: supplier: IT Support Services metadata: instructionCreatedBy: Jane Doe responses: '204': description: Successful request. We updated the funding instruction. '400': description: Validation error. content: application/problem+json: schema: type: object properties: *ref_9 required: *ref_10 examples: validationError: summary: Bad Request description: One or more validation errors occurred value: *ref_11 insufficientFunds: summary: Insufficient funds description: You do not have enough funds to complete the request. value: *ref_59 canNotBeModified: summary: Cannot be modified description: Resource cannot be modified. value: &ref_63 type: https://docs.payroc.com/api/errors#cannot-be-modified title: Cannot be modified status: 409 detail: You cannot modify this resource in its current state instructionIdError: summary: Bad request description: One or more validation errors occurred. value: *ref_60 fundingAccountsRestrcited: summary: Funding accounts restricted description: Funding accounts restricted. value: *ref_61 recipientAmountValueLimitExceeded: summary: Recipient amount.value limit exceeded description: One or more recipients exceed the 'amount.value' limit for your account value: *ref_62 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '404': description: Resource not found content: *ref_18 '500': description: An error has occured content: *ref_14 delete: summary: Delete funding instruction description: | > **Important:** You can delete a funding instruction only if its status is `accepted`. To view the status of a funding instruction, use our [Retrieve Funding Instruction](https://docs.payroc.com/api/schema/funding/funding-instructions/retrieve) method. Use this method to delete a funding instruction. To delete a funding instruction, you need its instructionId. Our gateway returned the instructionId in the response of the [Create Funding Instruction](https://docs.payroc.com/api/schema/funding/funding-instructions/create) method. **Note:** If you don't have the instructionId, use our [List Funding Instructions](https://docs.payroc.com/api/schema/funding/funding-instructions/list) method to search for the funding instruction. operationId: deleteInstructions tags: - Funding instructions responses: '204': description: Successful request. We deleted the funding instruction. '400': description: Validation error. content: application/problem+json: schema: type: object properties: *ref_9 required: *ref_10 examples: canNotBeModified: summary: Cannot be modified description: Resource cannot be modified. value: *ref_63 instructionIdError: summary: Bad request description: One or more validation errors occurred. value: *ref_60 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '404': description: Resource not found content: *ref_18 '500': description: An error has occured content: *ref_14 /funding-balance: get: tags: - Funding activity summary: List funding balances operationId: getFundingBalance description: | Use this method to return a [paginated](https://docs.payroc.com/api/pagination) list of funding balances available for each merchant linked to your account. Use query parameters to filter the list of results we return, for example, to search for the funding balance for a specific merchant. Our gateway returns the following information about each merchant in the list: - Total funds for the merchant. - Available funds that you can use for funding instructions. - Pending funds that we have not yet sent to funding accounts. parameters: - name: before in: query description: | Return the previous page of results before the value that you specify. You can’t send the before parameter in the same request as the after parameter. schema: *ref_32 examples: *ref_33 - name: after in: query description: | Return the next page of results after the value that you specify. You can’t send the after parameter in the same request as the before parameter. schema: *ref_34 examples: *ref_35 - name: limit in: query description: Limit the maximum number of results that we return for each page. schema: *ref_36 examples: *ref_37 - name: merchantId in: query description: Filter results by the unique identifier that the processor assigned to the merchant. schema: &ref_64 type: string examples: &ref_65 example: value: '4525644354' responses: '200': description: Successful request. Returns the funding balance available for each merchant. content: application/json: schema: type: object allOf: - type: object description: Contains the pagination properties that you use to navigate through a list of results. properties: *ref_38 - type: object properties: data: type: array description: Array of merchantBalance objects. items: type: object description: Object that contains information about the total funds available to the merchant. title: merchant balance properties: &ref_614 merchantId: type: string description: Unique identifier that the processor assigned to the merchant. example: '4525644354' funds: type: integer description: Total funding balance for the merchant, including pending amounts. The value is in the currency's lowest denomination, for example, cents. example: 120000 pending: type: number description: Amount of the funding balance that we have not yet sent to funding accounts. The value is in the currency's lowest denomination, for example, cents. example: 50050 available: type: number description: Amount of the funding balance that you can use in funding instructions. The value is in the currency's lowest denomination, for example, cents. example: 69950 currency: type: string description: Currency of the funding balance. We return a value of `USD`. example: USD required: - data examples: listSplitsExample: summary: Paginated list of merchant balances description: Paginated list of merchant balances. value: &ref_911 limit: 2 count: 2 hasMore: true links: - rel: previous method: get href: https://api.payroc.com/v1/funding-balance?before=4525644354&limit=2 - rel: next method: get href: https://api.payroc.com/v1/funding-balance?after=9876543219&limit=2 data: - merchantId: '4525644354' funds: 120000 pending: 50050 available: 69950 currency: USD - merchantId: '9876543219' funds: 50000 pending: 0 available: 50000 currency: USD noActivity: summary: No records found description: Valid request, but no records match the criteria. value: *ref_55 '400': description: Validation error. content: application/problem+json: schema: type: object properties: *ref_9 required: *ref_10 examples: paginationError: summary: Bad request description: One or more validation errors occurred value: type: https://docs.payroc.com/api/errors#bad-request title: Bad request status: 400 detail: One or more validation errors occurred, see error section for more info errors: - parameter: before detail: invalid value message: Expected integer, got abc '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '406': description: Not acceptable content: *ref_19 '500': description: An error has occured content: *ref_14 /funding-activity: get: tags: - Funding activity summary: List funding activity description: "Use this method to return a [paginated](https://docs.payroc.com/api/pagination) list of activity associated with your merchants' funding balances within a specific date range. \n\nUse query parameters to filter the list of results we return, for example, to view the activity for a specific merchant's funding balance. \n\nOur gateway returns the following information about each activity in the list:\n- Name of the merchant who owns the funding balance.\n-\tAmount of funds added or removed from the funding balance.\n-\tFunding account that received funds from the funding balance.\n" operationId: getFundingActivity parameters: - name: before in: query description: | Return the previous page of results before the value that you specify. You can’t send the before parameter in the same request as the after parameter. schema: *ref_32 examples: *ref_33 - name: after in: query description: | Return the next page of results after the value that you specify. You can’t send the after parameter in the same request as the before parameter. schema: *ref_34 examples: *ref_35 - name: limit in: query description: Limit the maximum number of results that we return for each page. schema: *ref_36 examples: *ref_37 - name: dateFrom in: query description: Filter by activity after a specific date. Send a value in **YYYY-MM-DD** format. required: true schema: &ref_361 type: string format: date examples: &ref_362 example: value: '2024-07-02' - name: dateTo in: query required: true description: Filter by activity before a specific date. Send a value in **YYYY-MM-DD** format. schema: &ref_363 type: string format: date examples: &ref_364 example: value: '2024-07-03' - name: merchantId in: query description: Filter results by the unique identifier that the processor assigned to the merchant. schema: *ref_64 examples: *ref_65 responses: '200': description: Successful request. Returns a list of funding activity. content: application/json: schema: type: object allOf: - type: object description: Contains the pagination properties that you use to navigate through a list of results. properties: *ref_38 - type: object properties: data: type: array description: Array of activityRecord objects. items: type: object description: Array of activityRecord objects. title: activity record properties: &ref_615 id: type: integer description: Unique identifier that we assigned to the activity. example: 12345 date: type: string format: datetime example: '2024-07-02T15:30:00Z' description: Date that we moved the funds. merchant: type: string description: Doing business as (DBA) name of the merchant that owns the funding balance. example: Pizza Doe recipient: type: string description: | Name of the account holder who owns the funding account that received funds. **Note:** We return a value for recipient only if the value for type is `debit`. example: Pizza Doe description: type: string example: payment description: Description of the activity. amount: type: number example: 4999 description: Total amount that we removed or added to the merchant's funding balance. The value is in the currency’s lowest denomination, for example, cents. type: type: string description: "Indicates if we moved funds into or out of the funding balance. Our gateway returns one of the following values:\n-\t`credit` - We moved funds into the funding balance. \n-\t`debit` - We moved funds out of the funding balance.\n" enum: - credit - debit example: credit currency: type: string description: Currency of the funds. We return a value of `USD`. example: USD required: &ref_616 - id - date - merchant - description - amount - type - currency required: - data examples: paginatedList: summary: Paginated activity records description: Valid payfac account with activity for date range. value: &ref_912 limit: 10 count: 10 hasMore: true links: - rel: previous method: get href: https://api.payroc.com/v1/funding-activity?before=11&limit=10&datefrom=2024-07-01&dateto=2024-07-03 - rel: next method: get href: https://api.payroc.com/v1/funding-activity?after=20&limit=10&datefrom=2024-07-01&dateto=2024-07-03 data: - id: 11 date: '2024-07-02T17:00:00.000Z' merchant: Pizza Doe description: sales type: credit amount: 4999 currency: USD - id: 12 date: '2024-07-02T19:32:00.000Z' merchant: Pizza Doe description: sales type: credit amount: 3999 currency: USD - id: 13 date: '2024-07-02T17:00:00.000Z' merchant: Pizza Doe description: sales type: credit amount: 3299 currency: USD - id: 14 date: '2024-07-02T17:00:00.000Z' merchant: Pizza Doe recipient: Payroc description: Interchange Fees type: debit amount: 50 currency: USD - id: 15 date: '2024-07-02T09:10:00.000Z' merchant: Pizza Doe description: sales type: credit amount: 4999 currency: USD - id: 16 date: '2024-07-02T17:00:00.000Z' merchant: Doe Hot Dogs description: Adjustment type: credit amount: 750 currency: USD - id: 17 date: '2024-07-02T17:00:00.000Z' merchant: Doe Hot Dogs recipient: Payroc description: Interchange Fees type: debit amount: 5 currency: USD - id: 18 date: '2024-07-02T17:00:00.000Z' merchant: Pizza Doe recipient: Payroc description: Charge back type: debit amount: 1000 currency: USD - id: 19 date: '2024-07-02T17:00:00.000Z' merchant: Pizza Doe description: sales type: credit amount: 5999 currency: USD - id: 20 date: '2024-07-02T17:00:00.000Z' merchant: Pizza Doe recipient: Pizza Doe description: payment type: debit amount: 1000 currency: USD noActivity: summary: No records found description: Valid request, but no records match the criteria. value: *ref_55 '400': description: Validation error. content: application/problem+json: schema: type: object properties: *ref_9 required: *ref_10 examples: parameterError: summary: Bad request description: One or more validation errors occurred. value: &ref_913 type: https://docs.payroc.com/api/errors#bad-request title: Bad request status: 400 detail: One or more validation errors occurred, see error section for more info. errors: - parameter: datefrom detail: invalid date message: Expected date, got "abc" paginationError: summary: Bad request description: One or more validation errors occurred value: &ref_904 type: https://docs.payroc.com/api/errors#bad-request title: Bad request status: 400 detail: One or more validation errors occurred, see error section for more info errors: - parameter: before detail: invalid value message: Expected integer, got abc outsideRecordRange: summary: Bad request description: Requested data outside allowed range. value: &ref_905 type: https://docs.payroc.com/api/errors#bad-request title: Bad request status: 400 detail: One or more validation errors occurred, see error section for more info errors: - parameter: datefrom detail: invalid date message: datefrom cannot be longer than two years ago. '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '406': description: Not acceptable content: *ref_19 '500': description: An error has occured content: *ref_14 /batches: get: tags: - Settlement summary: List batches description: "Use this method to return a [paginated](https://docs.payroc.com/api/pagination) list of batches that your merchants submitted to the processor on a specific date. \n\n**Note:** If you want to view the details of a specific batch and you have its batchId, use our [Retrieve Batch](https://docs.payroc.com/api/schema/reporting/settlement/retrieve-batch) method. \n\nUse query parameters to filter the list of results that we return, for example, to search for batches that were submitted by a specific merchant. \n\n> **Important:** You must provide a value for the date query parameter. \n\nOur gateway returns the following information about each batch in the list: \n-\tTransaction information, including the number of transactions and total value of sales. \n-\tMerchant information, including the merchant ID (MID) and the processing account that the batch is associated with. \n" operationId: getbatches parameters: - name: before in: query description: | Return the previous page of results before the value that you specify. You can’t send the before parameter in the same request as the after parameter. schema: *ref_32 examples: *ref_33 - name: after in: query description: | Return the next page of results after the value that you specify. You can’t send the after parameter in the same request as the before parameter. schema: *ref_34 examples: *ref_35 - name: limit in: query description: Limit the maximum number of results that we return for each page. schema: *ref_36 examples: *ref_37 - name: date in: query required: true description: Filter batches by the date that they were submitted. The format of this value is **YYYY-MM-DD**. schema: &ref_365 type: string format: date examples: &ref_366 example: value: '2027-07-02' - name: merchantId in: query description: Filter results by the unique identifier that the processor assigned to the merchant. schema: *ref_64 examples: *ref_65 responses: '200': description: Successful request. Returns a paginated list of batches. content: application/json: schema: type: object allOf: - type: object description: Contains the pagination properties that you use to navigate through a list of results. properties: *ref_38 - type: object properties: data: type: array description: Array of batch objects. items: type: object title: batch properties: &ref_66 batchId: type: integer description: Unique identifier that we assigned to the batch. example: 123 date: type: string format: date description: Date that the merchant submitted the batch. The format of this value is **YYYY-MM-DD**. example: '2024-07-02' createdDate: type: string format: date description: Date that we created a record for the batch. The format of this value is **YYYY-MM-DD**. example: '2024-07-02' lastModifiedDate: type: string format: date description: Date that the batch was last changed. The format of this value is **YYYY-MM-DD**. example: '2024-07-02' saleAmount: type: integer description: Total value of sales in the batch. We return the value in the currency's lowest denomination, for example, cents. heldAmount: type: integer description: Total value of authorizations in the batch. We return the value in the currency's lowest denomination, for example, cents. returnAmount: type: integer description: Total value of returns in the batch. We return the value in the currency's lowest denomination, for example, cents. transactionCount: type: integer description: Total number of transactions in the batch. currency: type: string description: Currency of the transactions in the batch. The value for the currency follows the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard. merchant: type: object title: merchant summary description: Object that contains information about the merchant. properties: &ref_68 merchantId: type: string description: Unique identifier that the processor assigned to the merchant. example: '4525644354' doingBusinessAs: type: string description: Trading name of the business. example: Pizza Doe processingAccountId: type: integer description: Unique identifier that we assigned to the processing account. example: 38765 link: type: object readOnly: true description: Object that contains HATEOAS links for the resource. properties: *ref_4 required: *ref_5 example: *ref_6 example: &ref_69 merchantId: '4525644354' doingBusinessAs: Pizza Doe processingAccountId: 38765 link: rel: processingAccount method: get href: https://api.payroc.com/v1/processing-accounts/38765 links: type: array items: type: object readOnly: true description: Object that contains HATEOAS links for the resource. properties: *ref_4 required: *ref_5 example: *ref_6 example: - rel: transactions method: get href: https://api.payroc.com/v1/transactions?batchId=123 - rel: authorizations method: get href: https://api.payroc.com/v1/authorizations?batchId=123 required: - data examples: paginatedList: summary: Paginated batches value: &ref_914 limit: 2 count: 2 hasMore: true links: - rel: previous method: get href: https://api.payroc.com/v1/batches?before=65&limit=2&date=2024-07-02 - rel: next method: get href: https://api.payroc.com/v1/batches?after=66&limit=2&&date=2024-07-02 data: - batchId: 65 date: '2024-07-02' createdDate: '2024-07-02' lastModifiedDate: '2024-07-02' saleAmount: 100 heldAmount: 0 returnAmount: 0 transactionCount: 10 currency: USD merchant: merchantId: '4525644354' doingBusinessAs: Pizza Doe processingAccountId: 38765 link: rel: processingAccount method: get href: https://api.payroc.com/v1/processing-accounts/38765 links: - rel: transactions method: get href: https://api.payroc.com/v1/transactions?batchId=65 - rel: authorizations method: get href: https://api.payroc.com/v1/authorizations?batchId=65 - batchId: 66 date: '2024-07-02' createdDate: '2024-07-02' lastModifiedDate: '2024-07-02' saleAmount: 76 heldAmount: 0 returnAmount: 12 transactionCount: 10 currency: USD merchant: merchantId: '9876543219' doingBusinessAs: Joe Bloggs Shoes processingAccountId: 68437 link: rel: processingAccount method: get href: https://api.payroc.com/v1/processing-accounts/68437 links: - rel: transactions method: get href: https://api.payroc.com/v1/transactions?batchId=66 - rel: authorizations method: get href: https://api.payroc.com/v1/authorizations?batchId=66 noActivity: summary: No records found description: Valid request, but no records match the criteria. value: *ref_55 '400': description: Validation error content: application/problem+json: schema: type: object properties: *ref_9 required: *ref_10 examples: parameterError: summary: Bad Request description: One or more validation errors occurred value: &ref_70 type: https://docs.payroc.com/api/errors#bad-request title: Bad request status: 400 detail: One or more validation errors occurred, see error section for more info errors: - parameter: date detail: invalid date message: Expected date, got "abc" paginationError: summary: Bad Request description: One or more validation errors occurred value: &ref_71 type: https://docs.payroc.com/api/errors#bad-request title: Bad request status: 400 detail: One or more validation errors occurred, see error section for more info errors: - parameter: before detail: invalid value message: Expected integer, got abc idError: summary: Bad Request description: One or more validation errors occurred value: &ref_67 type: https://docs.payroc.com/api/errors#bad-request title: Bad request status: 400 detail: One or more validation errors occurred, see error section for more info errors: - parameter: batchId detail: invalid value message: Expected integer, got abc '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '406': description: Not acceptable content: *ref_19 '500': description: An error has occured content: *ref_14 /batches/{batchId}: get: tags: - Settlement summary: Retrieve batch description: "Use this method to retrieve information about a batch. \n\n**Note:** To retrieve a batch, you need its batchId. If you don't have the batchId, use our [List Batches](https://docs.payroc.com/api/schema/reporting/settlement/list-batches) method to search for the batch. \n\nOur gateway returns the following information about the batch: \n\n-\tTransaction information, including the number of transactions and total value of sales. \n-\tMerchant information, including the merchant ID (MID) and the processing account that the batch is associated with. \n" operationId: getbatch parameters: - name: batchId in: path required: true description: Unique identifier that we assigned to the batch. style: simple schema: &ref_367 type: integer examples: &ref_368 example: value: 12345 responses: '200': description: Successful request. Returns the requested batch. content: application/json: schema: type: object title: batch properties: *ref_66 example: summary: Retrieved batch value: batchId: 65 date: '2024-07-02' createdDate: '2024-07-02' lastModifiedDate: '2024-07-02' saleAmount: 100 heldAmount: 0 returnAmount: 0 transactionCount: 10 currency: USD merchant: merchantId: '4525644354' doingBusinessAs: Pizza Doe processingAccountId: 38765 link: rel: processingAccount method: get href: https://api.payroc.com/v1/processing-accounts/38765 links: - rel: transactions method: get href: https://api.payroc.com/v1/transactions?batchId=65 - rel: authorizations method: get href: https://api.payroc.com/v1/authorizations?batchId=65 '400': description: Validation error content: application/problem+json: schema: type: object properties: *ref_9 required: *ref_10 examples: idError: summary: Bad Request description: One or more validation errors occurred value: *ref_67 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '404': description: Resource not found content: *ref_18 '406': description: Not acceptable content: *ref_19 '500': description: An error has occured content: *ref_14 /transactions: get: tags: - Settlement summary: List transactions description: "Use this method to return a paginated list of your merchants’ transactions. \n\n**Note:** If you want to view the details of a specific transaction and you have its transactionId, use our [Retrieve Transaction](https://docs.payroc.com/api/schema/reporting/settlement/retrieve-transaction) method. \n\nUse query parameters to filter the list of results that we return, for example, to search for transactions for a specific merchant. \n\n> **Important:** You must provide a value for either the date query parameter or the batchId query parameter. \n\nOur gateway returns the following information about each transaction in the list: \n\n-\tMerchant and processing account that ran the transaction. \n-\tTransaction type, date, amount, and the payment method that the customer used. \n-\tBatch that contains the transaction, and authorization details for the transaction. \n-\tProcessor that settled the transaction and the ACH deposit containing the transaction. \n" operationId: getTransactions parameters: - name: before in: query description: | Return the previous page of results before the value that you specify. You can’t send the before parameter in the same request as the after parameter. schema: *ref_32 examples: *ref_33 - name: after in: query description: | Return the next page of results after the value that you specify. You can’t send the after parameter in the same request as the before parameter. schema: *ref_34 examples: *ref_35 - name: limit in: query description: Limit the maximum number of results that we return for each page. schema: *ref_36 examples: *ref_37 - name: date in: query description: | Filter transactions by the date that the merchant submitted the batch that contains the transaction. The format of this value is **YYYY-MM-DD**. You must provide either the batchId or the date. schema: &ref_73 type: string format: date examples: &ref_74 example: value: '2024-07-02' - name: batchId in: query description: | Filter transactions by the unique identifier of the batch that contains the transaction. You must provide either the batchId or the date. schema: &ref_75 type: integer examples: &ref_76 example: value: 12345 - name: merchantId in: query description: Filter results by the unique identifier that the processor assigned to the merchant. schema: *ref_64 examples: *ref_65 - name: transactionType in: query description: Filter transactions by transaction type. schema: &ref_369 type: string enum: - Capture - Return examples: &ref_370 example: value: Capture responses: '200': description: Successful request. Returns a paginated list of transactions. content: application/json: schema: type: object allOf: - type: object description: Contains the pagination properties that you use to navigate through a list of results. properties: *ref_38 - type: object properties: data: type: array description: Array of transaction objects. items: type: object title: transaction description: Object that contains information about the transaction. properties: &ref_72 transactionId: type: - integer - 'null' description: Unique identifier that we assigned to the transaction. example: 442233 type: type: string description: | Indicates the type of transaction. The value is one of the following: - `capture` - Transaction is a sale. - `return` - Transaction is a refund. enum: - capture - return example: capture date: type: string format: date description: Date of the transaction. The format of this value is **YYYY-MM-DD**. example: '2024-07-02' amount: type: integer description: Transaction amount. We return the value in the currency's lowest denomination, for example, cents. example: 4999 entryMethod: type: - string - 'null' description: Indicates how the merchant received the payment details. enum: - barcodeRead - smartChipRead - swipedOriginUnknown - contactlessChip - ecommerce - manuallyEntered - manuallyEnteredFallback - swiped - swipedFallback - swipedError - scannedCheckReader - credentialOnFile - unknown example: contactlessChip createdDate: type: string format: date description: Date that we received the transaction. The format of this value is **YYYY-MM-DD**. example: '2024-07-02' lastModifiedDate: type: string format: date description: Date that the transaction was last changed. The format of this value is **YYYY-MM-DD**. example: '2024-07-02' status: type: string description: "Indicates the status of the transaction. The value is one of the following: \n\n-\t`fullSuspense` – Merchant ran the transaction while their account was in full suspense. \n-\t`heldAudited` – We have moved a transaction from fullSuspense and placed it on hold. \n-\t`heldReleasedAudited` – We audited and released the transaction that we had previously held. \n-\t`holdForSettlement30Days` - We are holding the transaction for a maximum of 30 days. \n-\t`holdForSettlementDuplicate` - We held the transaction because the transaction may be a duplicate. \n-\t`holdLongTerm` - We are holding the transaction for an extended period. \n-\t`paid` – We have paid the transaction funds to the merchant. \n-\t`paidByThirdParty` - A third party has paid the transaction funds to the merchant. \n-\t`partialRelease` – We partially released the transaction funds. \n-\t`pull` - We pulled the transaction, and the merchant does not receive funds for the transaction. \n-\t`release` - We released the transaction that we previously held. \n-\t`new` – We have prepared the funds from the transaction to send to the merchant. \n-\t`held` – We held the transaction. \n-\t`unknown` – No transaction status available. \n" enum: - fullSuspense - heldAudited - heldReleasedAudited - holdForSettlement30Days - holdForSettlementDuplicate - holdLongTerm - paid - paidByThirdParty - partialRelease - pull - release - new - held - unknown example: paid cashbackAmount: type: integer description: Cashback amount. We return the value in the currency's lowest denomination, for example, cents. example: 0 interchange: type: object description: Object that contains information about the interchange fees for the transaction. properties: basisPoint: type: integer description: Interchange basis points that we apply to the transaction. example: 150 transactionFee: type: integer description: Interchange fee for the transaction. We return the value in the currency's lowest denomination, for example, cents. example: 50 currency: type: string description: Currency of the transaction. The value for the currency follows the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard. example: USD merchant: type: object title: merchant summary description: Object that contains information about the merchant. properties: *ref_68 example: *ref_69 settled: type: object title: settlement summary description: Object that contains information about the settlement. properties: &ref_617 settledBy: type: string description: Processor that settled the transaction. example: Payroc achDate: type: string format: date description: Date that the processor settled the transaction. The format of this value is **YYYY-MM-DD**. example: '2024-07-02' achDepositId: type: integer description: Unique identifier of the ACH deposit. link: type: object readOnly: true description: Object that contains HATEOAS links for the resource. properties: *ref_4 required: *ref_5 example: *ref_6 example: &ref_618 settledBy: 3rd party achDate: '2024-07-02' achDepositId: 99 link: rel: achDeposit method: get href: https://api.payroc.com/v1/ach-deposits/99?merchantId=4525644354 batch: type: &ref_77 - object - 'null' title: batch summary description: Object that contains information about the batch. If we can't match a dispute to a batch, we don't return 'batch' object. properties: &ref_78 batchId: type: integer description: Unique identifier of the batch. example: 1234 date: type: string format: date description: Date that the merchant submitted the batch. example: '2024-07-02' cycle: type: string description: Indicates the cycle that contains the batch. example: am link: type: object readOnly: true description: Object that contains HATEOAS links for the resource. properties: *ref_4 required: *ref_5 example: *ref_6 card: type: object title: card summary description: Object that contains information about the card. properties: &ref_79 cardNumber: type: string 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`. example: 453985******7062 type: type: - string - 'null' description: | Card type, for example, Visa. **Note:** If we can’t match a dispute to a transaction, we don’t return a type object. enum: - visa - masterCard - discover - debit - ebt - wrightExpress - voyager - amex - privateLabel - storedValue - discoverRetained - jcbNonSettled - dinersClub - amexOptBlue - fuelman - unknown cvvPresenceIndicator: type: boolean description: Indicates whether the cardholder provided the Card Verification Value (CVV). avsRequest: type: boolean description: Indicates whether the merchant used the Address Verification Service (AVS) to verify the cardholder's address. avsResponse: type: string description: Response from the Address Verification Service (AVS). authorization: type: object title: authorization summary description: Object that contains information about the authorization. properties: &ref_619 authorizationId: type: integer description: Unique identifier of the authorization. example: 303101 code: type: string description: | Authorization code. **Note:** For returns, the card brands may not provide an authorization code. example: A1B2C3 amount: type: integer description: Authorization amount. We return the value in the currency's lowest denomination, for example, cents. example: 4999 avsResponseCode: type: string description: Response code that indicates if the address matches the address registered to the customer. example: 'Y' link: type: object readOnly: true description: Object that contains HATEOAS links for the resource. properties: *ref_4 required: *ref_5 example: *ref_6 required: - data examples: paginatedList: summary: Paginated transactions value: &ref_915 limit: 2 count: 1 hasMore: false links: - rel: previous method: get href: https://api.payroc.com/v1/transctions?before=442233&limit=2&date=2024-07-02 data: - transactionId: 442233 type: capture date: '2024-07-02' amount: 4999 entryMethod: ecommerce createdDate: '2024-07-02' lastModifiedDate: '2024-07-02' status: paid cashbackAmount: 0 interchange: basisPoint: 0 transactionFee: 0 currency: USD merchant: merchantId: '4525644354' doingBusinessAs: Pizza Doe processingAccountId: 38765 link: rel: processingAccount method: get href: https://api.payroc.com/v1/processing-accounts/38765 settled: settledBy: 3rd party achDate: '2024-07-02' achDepositId: 99 link: rel: achDeposit method: get href: https://api.payroc.com/v1/ach-deposits/99 batch: batchId: 12 date: '2024-07-02' cycle: am link: rel: batch method: get href: https://api.payroc.com/v1/batches/12 card: cardNumber: 453985******7062 type: visa cvvPresenceIndicator: true avsRequest: true avsResponse: '' authorization: authorizationId: 303101 code: A1B2C3 amount: 4999 avsResponseCode: '' link: rel: authorization method: get href: https://api.payroc.com/v1/authorizations/303101 noActivity: summary: No records found description: Valid request, but no records match the criteria. value: *ref_55 '400': description: Validation error content: application/problem+json: schema: type: object properties: *ref_9 required: *ref_10 examples: parameterError: summary: Bad Request description: One or more validation errors occurred value: *ref_70 paginationError: summary: Bad Request description: One or more validation errors occurred value: *ref_71 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '406': description: Not acceptable content: *ref_19 '500': description: An error has occured content: *ref_14 /transactions/{transactionId}: get: tags: - Settlement summary: Retrieve transaction description: "Use this method to retrieve information about a transaction. \n\n**Note:** To retrieve a transaction, you need its transactionId. If you don't have the transactionId, use our [List Transactions](https://docs.payroc.com/api/schema/reporting/settlement/list-transactions) method to search for the transaction. \n\nOur gateway returns the following information about the transaction: \n\n-\tMerchant and processing account that ran the transaction. \n-\tTransaction type, date, amount, and the payment method that the customer used. \n-\tBatch that contains the transaction, and authorization details for the transaction. \n-\tProcessor that settled the transaction and the ACH deposit containing the transaction. \n" operationId: gettransaction parameters: - name: transactionId description: Unique identifier of the transaction. in: path required: true schema: &ref_371 type: integer examples: &ref_372 example: value: 442233 responses: '200': description: Successful request. Returns the requested transaction. content: application/json: schema: type: object title: transaction description: Object that contains information about the transaction. properties: *ref_72 examples: retrievedTransaction: summary: Retrieve transaction value: &ref_916 transactionId: 442233 type: capture date: '2024-07-02' amount: 4999 entryMethod: ecommerce createdDate: '2024-07-02' lastModifiedDate: '2024-07-02' status: paid cashbackAmount: 0 interchange: basisPoint: 0 transactionFee: 0 currency: USD merchant: merchantId: '4525644354' doingBusinessAs: Pizza Doe processingAccountId: 38765 link: rel: processingAccount method: get href: https://api.payroc.com/v1/processing-accounts/38765 settled: settledBy: 3rd party achDate: '2024-07-02' achDepositId: 99 link: rel: achDeposit method: get href: https://api.payroc.com/v1/ach-deposits/99 batch: batchId: 12 date: '2024-07-02' cycle: am link: rel: batch method: get href: https://api.payroc.com/v1/batches/12 card: cardNumber: 453985******7062 type: visa cvvPresenceIndicator: true avsRequest: true avsResponse: '' authorization: authorizationId: 303101 code: A1B2C3 amount: 4999 avsResponseCode: '' link: rel: authorization method: get href: https://api.payroc.com/v1/authorizations/303101 '400': description: Validation error content: application/problem+json: schema: type: object properties: *ref_9 required: *ref_10 examples: transactionIdError: summary: Bad Request description: One or more validation errors occurred value: &ref_917 type: https://docs.payroc.com/api/errors#bad-request title: Bad request status: 400 detail: One or more validation errors occurred, see error section for more info errors: - parameter: transactionId detail: invalid value message: Expected integer, got abc '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '404': description: Resource not found content: *ref_18 '406': description: Not acceptable content: *ref_19 '500': description: An error has occured content: *ref_14 /authorizations: get: tags: - Settlement summary: List authorizations description: | Use this method to retrieve a [paginated](https://docs.payroc.com/api/pagination) list of authorizations. Use query parameters to filter the list of results that we return, for example, to search for authorizations linked to a specific merchant. > **Important:** You must provide a value for either the date query parameter or the batchId query parameter. Our gateway returns the following information about each authorization in the list: - Authorization response from the issuing bank. - Amount that the issuing bank authorized. - Merchant that ran the authorization. - Details about the customer's card, the transaction, and the batch. operationId: getAuthorizations parameters: - name: before in: query description: | Return the previous page of results before the value that you specify. You can’t send the before parameter in the same request as the after parameter. schema: *ref_32 examples: *ref_33 - name: after in: query description: | Return the next page of results after the value that you specify. You can’t send the after parameter in the same request as the before parameter. schema: *ref_34 examples: *ref_35 - name: limit in: query description: Limit the maximum number of results that we return for each page. schema: *ref_36 examples: *ref_37 - name: date in: query description: | Filter transactions by the date that the merchant submitted the batch that contains the transaction. The format of this value is **YYYY-MM-DD**. You must provide either the batchId or the date. schema: *ref_73 examples: *ref_74 - name: batchId in: query description: | Filter transactions by the unique identifier of the batch that contains the transaction. You must provide either the batchId or the date. schema: *ref_75 examples: *ref_76 - name: merchantId in: query description: Filter results by the unique identifier that the processor assigned to the merchant. schema: *ref_64 examples: *ref_65 responses: '200': description: Successful request. Returns a paginated list of authorizations. content: application/json: schema: type: object allOf: - type: object description: Contains the pagination properties that you use to navigate through a list of results. properties: *ref_38 - type: object properties: data: type: array description: Array of authorization objects. items: type: object title: authorization description: Object that contains information about the authorization. properties: &ref_80 authorizationId: type: integer description: Unique identifier that we assigned to the authorization. example: 12345 createdDate: type: string format: date description: Date that we received the authorization. The format of this value is **YYYY-MM-DD**. example: '2024-01-30' lastModifiedDate: type: string format: date description: Date that the authorization was last changed. The format of this value is **YYYY-MM-DD**. example: '2024-01-30' authorizationResponse: type: string description: Response from the issuing bank for the authorization. enum: - activityCountLimitExceeded - alreadyReversed - approved - approveVip - approveWithId - cannotVerifyPin - cardAuthenticationFailed - cardTypeVerificationError - cashRequestExceedsIssuerLimit - cashServiceNotAvailable - cidVerificationError - contactCardIssuer - cryptographicFailure - dailyThresholdExceeded - declineCvv2Failure - deny - denyAccountCanceled - denyClosedMerchant - denyNewCardIssued - denyPickUpCard - destinationCannotBeFoundForRouting - doNotHonor - duplicateTransmissionDetected - error - exceedsWithdrawalAmountLimit - expiredCard - fileTemporarilyUnavailable - forceStip - formatError - forwardToIssuer - functionNotSupported - honorWithId - incorrectCvv - incorrectPin - ineligibleForResubmission - insufficientFunds - invalidAccount - invalidAccountNumber - invalidAmount - invalidAuthorizationLifeCycle - invalidBillerInformation - invalidCardSecurityCode - invalidCurrencyCode - invalidMerchant - invalidResponse - invalidTransaction - issuerNotAvailable - issuerTimeout - issuerUnavailable - noActionTaken - noCardRecord - noCheckingAccount - noCreditAccount - noFinancialImpact - noReasonToDecline - noSavingsAccount - noSuchIssuer - partialApproval - partialAuthorization - pickUpCard - pickUpCardSpecialCondition - pinChangeRequestDeclined - pinCryptographicErrorFound - pinEntryTriesExceeded - pinNotChanged - pleaseCallIssuer - reenterTransaction - referToCardIssuer - referToCardIssuerSpecialCondition - restrictedCard - reversal - reversalDataInconsistent - revokeAllAuthorizationsOrder - scheduledTransactionstoppedByCardholder - securityViolation - successful - surchargeAmountNotPermitted - suspectFraud - systemMalfunction - transactionAmountExceedsApprovalAmount - transactionCannotBeCompleted - transactionNotAllowedAtMerchant - transactionNotAllowedAtTerminal - transactionNotPermitted - transactionNotPermittedToCardholder - unableToGoOnline - unableToLocateRecordInFile - unableToVerifyPin - unacceptablePin - unknown - unsafePin preauthorizationRequestAmount: type: integer description: Amount that the merchant requested for the authorization. We return the value in the currency's lowest denomination, for example, cents. example: 10000 currency: type: string description: Currency of the authorization. The value for the currency follows the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard. batch: type: *ref_77 title: batch summary description: Object that contains information about the batch. If we can't match a dispute to a batch, we don't return 'batch' object. properties: *ref_78 card: type: object title: card summary description: Object that contains information about the card. properties: *ref_79 merchant: type: object title: merchant summary description: Object that contains information about the merchant. properties: *ref_68 example: *ref_69 transaction: type: object title: transaction summary description: Object that contains summary information about the transaction that the dispute is linked to. properties: &ref_81 transactionId: type: - integer - 'null' description: Unique identifier of the transaction. If we can't match a dispute to a transaction, we don't return the transactionId or link object. example: 12345 type: type: string description: Indicates the type of transaction. enum: - capture - return date: type: string format: date description: Date of the transaction. The format of this value is **YYYY-MM-DD**. example: '2024-07-02' entryMethod: type: - string - 'null' description: Describes how the merchant received the payment details. If we can't match a dispute to a transaction, we don't return an entryMethod object. enum: - barcodeRead - smartChipRead - swipedOriginUnknown - contactlessChip - ecommerce - manuallyEntered - manuallyEnteredFallback - swiped - swipedFallback - swipedError - scannedCheckReader - credentialOnFile - unknown amount: type: integer description: Total amount of the transaction. The value is in the currency's lowest denomination, for example, cents. example: 25000 link: type: object readOnly: true description: Object that contains HATEOAS links for the resource. properties: *ref_4 required: *ref_5 example: *ref_6 required: - data examples: paginatedList: summary: Paginated authorizations value: &ref_918 limit: 2 count: 1 hasMore: false links: - rel: previous method: get href: https://api.payroc.com/v1/authorizations?before=65&limit=2&date=2024-07-02 data: - authorizationId: 65 createdDate: '2024-07-02' lastModifiedDate: '2024-07-02' authorizationResponse: successful preauthorizationRequestAmount: 10000 currency: USD merchant: merchantId: '4525644354' doingBusinessAs: Pizza Doe processingAccountId: 38765 link: rel: processingAccount method: get href: https://api.payroc.com/v1/processing-accounts/38765 batch: batchId: 12 date: '2024-07-02' cycle: am link: rel: batch method: get href: https://api.payroc.com/v1/batches/12 card: cardNumber: 12456**********4124 type: visa cvvPresenceIndicator: true avsRequest: true avsResponse: 'Y' transaction: transactionId: 12345 type: capture date: '2024-07-02' entryMethod: swiped amount: 100 link: rel: transaction method: get href: https://api.payroc.com/v1/transactions/12345 noActivity: summary: No records found description: Valid request, but no records match the criteria. value: *ref_55 '400': description: Validation error content: application/problem+json: schema: type: object properties: *ref_9 required: *ref_10 examples: parameterError: summary: Bad Request description: One or more validation errors occurred value: *ref_70 paginationError: summary: Bad Request description: One or more validation errors occurred value: *ref_71 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '406': description: Not acceptable content: *ref_19 '500': description: An error has occured content: *ref_14 /authorizations/{authorizationId}: get: tags: - Settlement summary: Retrieve authorization description: | Use this method to retrieve information about an authorization. **Note:** To retrieve an authorization, you need its authorizationId. If you don't have the authorizationId, use our [List Authorizations](https://docs.payroc.com/api/schema/reporting/settlement/list-authorizations) method to search for the authorization. Our gateway returns the following information about the authorization: - Authorization response from the issuing bank. - Amount that the issuing bank authorized. - Merchant that ran the authorization. - Details about the customer's card, the transaction, and the batch. operationId: getAuthorization parameters: - name: authorizationId description: Unique identifier of the authorization. in: path required: true schema: &ref_373 type: integer examples: &ref_374 example: value: 12345 responses: '200': description: Successful request. Returns the requested authorization. content: application/json: schema: type: object title: authorization description: Object that contains information about the authorization. properties: *ref_80 examples: retrievedAuthorization: summary: Retrieve authorization value: &ref_919 authorizationId: 65 createdDate: '2024-07-02' lastModifiedDate: '2024-07-02' authorizationResponse: successful preauthorizationRequestAmount: 10000 currency: USD merchant: merchantId: '4525644354' doingBusinessAs: Pizza Doe processingAccountId: 38765 link: rel: processingAccount method: get href: https://api.payroc.com/v1/processing-accounts/38765 batch: batchId: 12 date: '2024-07-02' cycle: am link: rel: batch method: get href: https://api.payroc.com/v1/batches/12 card: cardNumber: 453985******7062 type: visa cvvPresenceIndicator: true avsRequest: true avsResponse: 'Y' transaction: transactionId: 442233 type: capture date: '2024-07-02' entryMethod: swiped amount: 100 link: rel: transaction method: get href: https://api.payroc.com/v1/transactions/12345 '400': description: Invalid request content: *ref_15 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '404': description: Resource not found content: *ref_18 '406': description: Not acceptable content: *ref_19 '500': description: An error has occured content: *ref_14 /disputes: get: tags: - Settlement summary: List disputes description: | Use this method to return a [paginated](https://docs.payroc.com/api/pagination) list of disputes. Use query parameters to filter the list of results that we return, for example, to search for disputes linked to a specific merchant. > **Important:** You must provide a value for the date query parameter. Our gateway returns the following information about each dispute in the list: - Its status, type, and description. - Transaction that the dispute is linked to, including the transaction date, merchant who ran the transaction, and the payment method that the cardholder used. operationId: getdisputes parameters: - name: before in: query description: | Return the previous page of results before the value that you specify. You can’t send the before parameter in the same request as the after parameter. schema: *ref_32 examples: *ref_33 - name: after in: query description: | Return the next page of results after the value that you specify. You can’t send the after parameter in the same request as the before parameter. schema: *ref_34 examples: *ref_35 - name: limit in: query description: Limit the maximum number of results that we return for each page. schema: *ref_36 examples: *ref_37 - name: date in: query required: true description: Filter results by the date that the dispute was submitted. schema: &ref_375 type: string format: date examples: &ref_376 example: value: '2024-07-02' - name: merchantId in: query description: Filter results by the unique identifier that the processor assigned to the merchant. schema: *ref_64 examples: *ref_65 responses: '200': description: Successful request. Returns a paginated list of disputes. content: application/json: schema: type: object allOf: - type: object description: Contains the pagination properties that you use to navigate through a list of results. properties: *ref_38 - type: object properties: data: type: array description: Array of dispute objects. items: type: object title: dispute description: Object that contains information about the dispute. properties: &ref_620 disputeId: type: integer description: Unique identifier that we assigned to the dispute. example: 12345 disputeType: type: string description: Type of dispute. enum: - prearbitration - issuerReversal - firstDisputeWithReversal - firstDispute currentStatus: description: Object that contains information about the current status of the dispute. allOf: - type: object title: dispute status description: Object that contains information about the current status of the dispute. properties: &ref_82 disputeStatusId: type: integer description: Unique identifier that we assigned to the status of the dispute. example: 12345 status: type: string description: | Status of the dispute. **Note:** If you want to view the status history of the dispute, use our [List Dispute Statuses](https://docs.payroc.com/api/schema/reporting/settlement/list-disputes-statuses) method. enum: - prearbitrationInProcess - prearbitrationAccepted - prearbitrationDeclined - arbitrationFiledWithCardBand - arbitrationFundsToBeReturned - arbitrationLost - arbitrationSettledPartialAmount - precomplianceInProcess - precomplianceAccepted - precomplianceDeclined - complianceFiledWithCardBand - complianceLost - complianceSettledPartialAmount - invalid - issuerReversal - new - rejected - representmentInProgress - representmentFailed - representmentPaid - representmentReceived - stand statusDate: type: string format: date description: Date that the status of the dispute was last changed. The format of this value is **YYYY-MM-DD**. example: '2024-02-01' - type: object properties: link: type: object readOnly: true description: Object that contains HATEOAS links for the resource. properties: *ref_4 required: *ref_5 example: *ref_6 createdDate: type: string format: date description: Date that we received the dispute. The format of this value is **YYYY-MM-DD**. example: '2024-02-20' lastModifiedDate: type: string format: date description: Date that the dispute was last changed. The format of this value is **YYYY-MM-DD**. example: '2024-02-25' receivedDate: type: string format: date description: Date that the acquiring bank received the dispute. The format of this value is **YYYY-MM-DD**. example: '2024-02-18' description: type: string description: Description of the dispute. referenceNumber: type: string description: Reference number from the acquiring bank. disputeAmount: type: integer description: Dispute amount. We return the value in the currency's lowest denomination, for example, cents. feeAmount: type: integer description: Value of the fees for the dispute. We return the value in the currency's lowest denomination, for example, cents. firstDispute: type: boolean description: Indicates if this is the first dispute for the transaction. example: true authorizationCode: type: string description: Authorization code of the transaction that the dispute is linked to. currency: type: string description: Currency of the transaction that the dispute is linked to. The value for the currency follows the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard. card: type: object title: card summary description: Object that contains information about the card. properties: *ref_79 merchant: type: object title: merchant summary description: Object that contains information about the merchant. properties: *ref_68 example: *ref_69 transaction: type: object title: transaction summary description: Object that contains summary information about the transaction that the dispute is linked to. properties: *ref_81 required: - data examples: paginatedList: summary: Paginated disputes value: &ref_920 limit: 2 count: 1 hasMore: false links: - rel: previous method: get href: https://api.payroc.com/v1/disputes?before=65&limit=2&date=2024-07-02 data: - disputeId: 65 disputeType: firstDispute currentStatus: disputeStatusId: 123 status: new statusDate: '2024-07-02' link: rel: statuses method: get href: https://api.payroc.com/v1/disputes/65/statuses createdDate: '2024-07-02' lastModifiedDate: '2024-07-02' receivedDate: '2024-07-02' description: '' referenceNumber: '35435435' disputeAmount: 1000 feeAmount: 100 firstDispute: true authorizationCode: '574254' currency: USD merchant: merchantId: '4525644354' doingBusinessAs: Pizza Doe processingAccountId: 38765 link: rel: merchant method: get href: https://api.payroc.com/v1/processing-accounts/38765 card: cardNumber: 12456**********4124 type: visa cvvPresenceIndicator: true avsRequest: true avsResponse: '' transaction: transactionId: 12345 type: capture date: '2024-07-02' entryMethod: swiped amount: 100 link: rel: transaction method: get href: https://api.payroc.com/v1/transactions/12345 noActivity: summary: No records found description: Valid request, but no records match the criteria. value: *ref_55 '400': description: Validation error content: application/problem+json: schema: type: object properties: *ref_9 required: *ref_10 examples: parameterError: summary: Bad Request description: One or more validation errors occurred value: *ref_70 paginationError: summary: Bad Request description: One or more validation errors occurred value: *ref_71 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '406': description: Not acceptable content: *ref_19 '500': description: An error has occured content: *ref_14 /disputes/{disputeId}/statuses: get: tags: - Settlement summary: List dispute statuses description: | Use this method to return the status history of a dispute. To view the status history of a dispute, you need its disputeId. If you don't have the disputeId, use our [List Disputes](https://docs.payroc.com/api/schema/reporting/settlement/list-disputes) method to search for the dispute. Our gateway returns a list that contains each status change, the date it was changed, and its updated status. operationId: getdisputesStatuses parameters: - name: disputeId description: Unique identifier of the dispute. in: path required: true schema: &ref_377 type: integer examples: &ref_378 example: value: 12345 responses: '200': description: Successful request. Returns the status history for a specific dispute. content: application/json: schema: type: array description: Collection of status items: type: object title: dispute status description: Object that contains information about the current status of the dispute. properties: *ref_82 '400': description: Validation error content: application/problem+json: schema: type: object properties: *ref_9 required: *ref_10 examples: parameterError: summary: Bad Request description: One or more validation errors occurred value: *ref_70 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '404': description: Resource not found content: *ref_18 '406': description: Not acceptable content: *ref_19 '500': description: An error has occured content: *ref_14 /processing-terminals/{processingTerminalId}/payment-links: post: tags: - Payment links summary: Create payment link description: | Use this method to create a payment link that a customer can use to make a payment for goods or services. The request includes the following settings: - **type** - Indicates whether the link can be used only once or if it can be used multiple times. - **authType** - Indicates whether the transaction is a sale or a pre-authorization. - **paymentMethod** - Indicates the payment methods that the merchant accepts. - **charge** - Indicates whether the merchant or the customer enters the amount for the transaction. If your request is successful, our gateway returns a paymentLinkId, which you can use to perform follow-on actions. **Note:** To share the payment link with a customer, use our [Share Payment Link](https://docs.payroc.com/api/schema/payment-links/sharing-events/share) method. operationId: createPaymentLink parameters: - name: Idempotency-Key in: header required: true 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). schema: *ref_22 examples: *ref_23 - name: processingTerminalId in: path required: true description: Unique identifier that we assigned to the terminal. schema: &ref_96 maxLength: 50 minLength: 4 type: string examples: &ref_97 example: value: '1234001' requestBody: description: "Polymorphic object that contains payment link information. \n\nThe value of the type parameter determines which variant you should use:\n-\t`multiUse` - Create a link that the merchant can use to take multiple payments.\n-\t`singleUse` - Create a link that the merchant can use for only one payment.\n" content: application/json: schema: type: object oneOf: - required: &ref_92 - type - order - authType - paymentMethods - merchantReference type: object title: multiUse description: Object that contains information about a multi-use payment link. properties: &ref_93 type: type: string description: | Type of link. The merchant can use a multi-use link to take multiple payments. enum: - multiUse example: multiUse paymentLinkId: type: string minLength: 10 maxLength: 10 readOnly: true description: Unique identifier that we assigned to the payment link. example: JZURRJBUPS merchantReference: type: string minLength: 1 maxLength: 48 description: Unique identifier that the merchant assigned to the payment. example: LinkRef6543 order: required: &ref_621 - charge type: object description: Object that contains information about the order. properties: &ref_622 description: type: string maxLength: 1024 description: A brief description of the transaction. example: Pie It Forward charitable trust donation charge: type: object description: "Polymorphic object that indicates who enters the amount for the payment link. \n\nThe value of the type parameter determines which variant you should use: \n-\t`prompt` - Customer enters the amount.\n-\t`preset` - Merchant sets the amount. \n" oneOf: - required: &ref_84 - type - currency type: object title: prompt description: Object that contains information about the charge when the customer enters the amount of the transaction. properties: &ref_85 type: type: string enum: - prompt example: prompt currency: example: USD type: string description: Currency of the transaction. The value for the currency follows the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard. enum: &ref_83 - 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 - required: &ref_86 - type - amount - currency type: object title: preset description: Object that contains information about the charge when the merchant enters the amount of the transaction. properties: &ref_87 type: type: string enum: - preset example: preset amount: type: integer format: int64 description: Total amount of the transaction. The value is in the currency's lowest denomination, for example, cents. example: 4999 currency: example: USD type: string description: Currency of the transaction. The value for the currency follows the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard. enum: *ref_83 authType: type: string description: Type of transaction. enum: - sale - preAuthorization example: sale paymentMethods: type: array uniqueItems: true description: | Payment methods that the merchant accepts. **Note:** If a payment is a pre-authorization, the customer must pay by card. items: type: string enum: - card - bankTransfer example: - card customLabels: type: array uniqueItems: true description: | Array of customLabel objects. **Note:** You can change the label of the payment button only. items: type: object description: Object that contains the information for the custom label. properties: &ref_88 element: type: string description: Element that you want to provide a custom label for. enum: - paymentButton example: paymentButton label: type: string minLength: 1 maxLength: 24 description: Custom label to display on the element. example: SUPPORT US assets: required: &ref_89 - paymentUrl - paymentButton type: object readOnly: true description: Object that contains shareable assets for the payment link. properties: &ref_90 paymentUrl: type: string description: URL of the payment link. example: https://payments.payroc.com/merchant/pay-by-link?token=7c2fc08c-cb0e-44ba-8bcd-cf6de6eb3206 paymentButton: type: string format: html description: HTML code for the payment link. You can embed the HTML code in the merchant's website. example: | Pay Now status: type: string readOnly: true description: | Status of the payment link. The value is one of the following: - `active` - Payment link is active. - `completed` - Customer has paid. - `deactivated` - Merchant has deactivated the link. - `expired` - Payment link has expired. enum: - active - completed - deactivated - expired example: active createdOn: type: string format: date readOnly: true description: Date that the merchant created the link. The format of this value is **YYYY-MM-DD**. example: '2024-07-02' expiresOn: type: string format: date description: Last date that the customer can use the payment link. The format of this value is **YYYY-MM-DD**. example: '2024-08-02' credentialOnFile: type: object description: Object that contains information about saving the customer’s payment details. properties: &ref_91 tokenize: type: boolean description: Indicates if our gateway should tokenize the customer’s payment details as part of the transaction. example: true mitAgreement: type: string default: unscheduled description: | Indicates how the merchant can use the customer’s card details, as agreed by the customer: - `unscheduled` - Transactions for a fixed or variable amount that are run at a certain pre-defined event. - `recurring` - Transactions for a fixed amount that are run 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 are run 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. enum: - unscheduled - recurring - installment example: recurring - required: &ref_94 - type - order - authType - expiresOn - paymentMethods - merchantReference type: object title: singleUse description: Object that contains information about a single-use payment link. properties: &ref_95 type: type: string description: Type of link. The merchant can use this link for only one payment. enum: - singleUse example: singleUse paymentLinkId: type: string minLength: 10 maxLength: 10 readOnly: true description: Unique identifier that we assigned to the payment link. example: CKHP6VVWYT merchantReference: type: string minLength: 1 maxLength: 48 description: Unique identifier that the merchant assigned to the payment. example: LinkRef7654 order: required: &ref_623 - orderId - charge type: object description: Object that contains information about the order. properties: &ref_624 orderId: maxLength: 24 minLength: 1 type: string description: Unique identifier that the merchant assigned to the order. example: OrderRef7654 description: type: string maxLength: 1024 description: A brief description of the transaction. example: Large Pepperoni Pizza charge: type: object description: "Polymorphic object that indicates who enters the amount for the payment link. \n\nThe value of the type parameter determines which variant you should use: \n-\t`prompt` - Customer enters the amount.\n-\t`preset` - Merchant sets the amount. \n" oneOf: - required: *ref_84 type: object title: prompt description: Object that contains information about the charge when the customer enters the amount of the transaction. properties: *ref_85 - required: *ref_86 type: object title: preset description: Object that contains information about the charge when the merchant enters the amount of the transaction. properties: *ref_87 authType: type: string description: Type of transaction. enum: - sale - preAuthorization example: sale paymentMethods: type: array uniqueItems: true description: | Payment methods that the merchant accepts. **Note:** If the payment is a pre-authorization, the customer must pay by card. items: type: string enum: - card - bankTransfer example: - card customLabels: type: array uniqueItems: true description: | Array of customLabel objects. **Note:** You can change the label of the payment button only. items: type: object description: Object that contains the information for the custom label. properties: *ref_88 assets: required: *ref_89 type: object readOnly: true description: Object that contains shareable assets for the payment link. properties: *ref_90 status: type: string readOnly: true description: | Status of the payment link. The value is one of the following: - `active` - Payment link is active. - `completed` - Customer has paid. - `deactivated` - Merchant has deactivated the link. - `expired` - Payment link has expired. enum: - active - completed - deactivated - expired example: active createdOn: type: string format: date readOnly: true description: Date that the merchant created the link. The format of this value is **YYYY-MM-DD**. example: '2024-07-02' expiresOn: type: string format: date description: Last date that the customer can use the payment link. The format of this value is **YYYY-MM-DD**. example: '2024-08-02' credentialOnFile: type: object description: Object that contains information about saving the customer’s payment details. properties: *ref_91 examples: multiUsePaymentLinkRequest: summary: Multi-use payment link. description: Create a multi-use payment link. value: &ref_922 type: multiUse merchantReference: LinkRef6543 order: description: Pie It Forward charitable trust donation charge: type: prompt currency: USD authType: sale paymentMethods: - card - bankTransfer customLabels: - element: paymentButton label: SUPPORT US singleUsePaymentLinkRequest: summary: Single-use payment link. description: Create a single-use payment link. value: &ref_923 type: singleUse merchantReference: LinkRef7654 order: orderId: OrderRef7654 description: Large Pepperoni Pizza charge: type: preset amount: 4999 currency: USD authType: sale paymentMethods: - card customLabels: - element: paymentButton label: PAY NOW expiresOn: '2024-08-02' required: true responses: '201': description: "Successful request. We return a polymorphic object that contains payment link information.\nThe value of the type parameter determines which variant you should use:\n-\t`multiUse` - Create a link that the merchant can use to take multiple payments.\n-\t`singleUse` - Create a link that the merchant can use for only one payment.\n" content: application/json: schema: type: object oneOf: - required: *ref_92 type: object title: multiUse description: Object that contains information about a multi-use payment link. properties: *ref_93 - required: *ref_94 type: object title: singleUse description: Object that contains information about a single-use payment link. properties: *ref_95 examples: createdPaymentLink: summary: Payment Link description: Active multi-use payment link. value: &ref_98 type: multiUse paymentLinkId: JZURRJBUPS merchantReference: LinkRef6543 order: description: Pie It Forward charitable trust donation charge: type: prompt currency: USD authType: sale paymentMethods: - card - bankTransfer customLabels: - element: paymentButton label: SUPPORT US assets: paymentUrl: https://payments.payroc.com/merchant/pay-by-link?token=02ada211-ff51-4845-b0b5-e685aeb4b19d paymentButton: | SUPPORT US status: active createdOn: '2024-09-24' headers: location: description: URI reference to created resource. schema: *ref_24 examples: *ref_25 '400': description: Validation error content: application/problem+json: schema: type: object properties: *ref_9 required: *ref_10 examples: validationError: summary: Bad Request description: One or more validation errors occurred value: *ref_11 idempotentKeyMissing: summary: Idempotency key missing description: Idempotency key must be supplied value: *ref_26 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '404': description: Resource not found content: *ref_18 '406': description: Not acceptable content: *ref_19 '409': description: Conflict content: &ref_104 application/problem+json: schema: type: object properties: *ref_27 required: *ref_28 examples: resourceExists: summary: Resource already exists description: Resource already exists value: &ref_924 type: https://docs.payroc.com/api/errors#resource-already-exists title: Resource already exists status: 409 detail: The resource you attempted to create already exists instance: https://api.payroc.com/v1/merchant/12345 '415': description: Unsupported media type content: &ref_105 application/problem+json: schema: type: object properties: &ref_539 type: type: string description: URI reference identifying the problem type example: https://docs.payroc.com/api/errors#unsupported-media-type title: type: string description: Short description of the issue. example: Unsupported media type status: type: integer description: Http status code example: 415 detail: type: string description: Explanation of the problem example: You submitted a payload in an unsupported format. required: &ref_540 - type - title - status - detail examples: unsupportedMediaType: summary: Unsupported media type description: The payload is in an unsupported format. value: &ref_925 type: https://docs.payroc.com/api/errors#unsupported-media-type title: Unsupported media type status: 415 detail: You submitted a payload in an unsupported format '500': description: An error has occured content: *ref_14 get: tags: - Payment links summary: List payment links description: | Use this method to return a [paginated](https://docs.payroc.com/api/pagination) list of payment links linked to a processing terminal. **Note:** If you want to view the details of a specific payment link and you have its paymentLinkId, use our [Retrieve Payment Link](https://docs.payroc.com/api/schema/payment-links/retrieve) method. Use query parameters to filter the list of results that we return, for example, to search for only active links or multi-use links. Our gateway returns the following information about each payment link in the list: - **type** - Indicates whether the link can be used only once or if it can be used multiple times. - **authType** - Indicates whether the transaction is a sale or a pre-authorization. - **paymentMethods** - Indicates the payment method that the merchant accepts. - **charge** - Indicates whether the merchant or the customer enters the amount for the transaction. - **status** - Indicates if the payment link is active. For each payment link, we also return a paymentLinkId, which you can use for follow-on actions. operationId: listPaymentLinks parameters: - name: processingTerminalId in: path required: true description: Unique identifier that we assigned to the terminal. schema: *ref_96 examples: *ref_97 - name: merchantReference in: query description: Filter results by the unique identifier that the merchant assigned to the payment link. schema: &ref_379 type: string minLength: 1 maxLength: 48 examples: &ref_380 example: value: LinkRef6543 - name: linkType in: query description: Filter results by the type of link. Send a value of singleUse or multiUse. schema: &ref_381 type: string enum: - multiUse - singleUse examples: &ref_382 example: value: multiUse - name: chargeType in: query description: | Filter results by the user that entered the amount. Send one of the following values: - prompt - Customer entered the amount. - preset - Merchant entered the amount. schema: &ref_383 type: string enum: - preset - prompt examples: &ref_384 example: value: prompt - name: status in: query description: Filter results by the status of the payment link. Send a value of active, completed,deactived, or expired. schema: &ref_385 type: string enum: - active - completed - deactivated - expired examples: &ref_386 example: value: active - name: recipientName in: query description: Filter results by the customer's name. schema: &ref_108 type: string minLength: 1 maxLength: 48 examples: &ref_109 example: value: Sarah Hazel Hopper - name: recipientEmail in: query description: Filter results by the customer's email address. schema: &ref_110 type: string minLength: 6 maxLength: 128 examples: &ref_111 example: value: sarah.hopper@example.com - name: createdOn in: query description: Filter results by the link's created date. Send a value in **YYYY-MM-DD** format. schema: &ref_387 type: string format: date examples: &ref_388 example: value: '2024-07-02' - name: expiresOn in: query description: Filter results by the link's expiry date. Send a value in **YYYY-MM-DD** format. schema: &ref_389 type: string format: date examples: &ref_390 example: value: '2024-08-02' - name: before in: query description: | Return the previous page of results before the value that you specify. You can’t send the before parameter in the same request as the after parameter. schema: *ref_32 examples: *ref_33 - name: after in: query description: | Return the next page of results after the value that you specify. You can’t send the after parameter in the same request as the before parameter. schema: *ref_34 examples: *ref_35 - name: limit in: query description: Limit the maximum number of results that we return for each page. schema: *ref_36 examples: *ref_37 responses: '200': description: Successful request. Returns a [paginated](https://docs.payroc.com/api/pagination) list of payment links. content: application/json: schema: required: &ref_625 - count - data - hasMore - limit type: object allOf: &ref_626 - type: object description: Contains the pagination properties that you use to navigate through a list of results. properties: *ref_38 - type: object properties: data: type: array description: "Array of polymorphic objects that contains payment link information. \n\nThe value of the type parameter determines which variant you should use: \n-\t'multiUse' - Create a link that the merchant can use to take multiple payments.\n-\t'singleUse' - Create a link that the merchant can use for only one payment.\n" items: type: object oneOf: - required: *ref_92 type: object title: multiUse description: Object that contains information about a multi-use payment link. properties: *ref_93 - required: *ref_94 type: object title: singleUse description: Object that contains information about a single-use payment link. properties: *ref_95 examples: paginatedResults: summary: Payment links description: Paginated list of payment links value: &ref_921 limit: 2 count: 2 hasMore: true data: - type: multiUse paymentLinkId: JZURRJBUPS merchantReference: LinkRef6543 order: description: Pie It Forward charitable trust donation charge: type: prompt currency: USD authType: sale paymentMethods: - card - bankTransfer customLabels: - element: paymentButton label: SUPPORT US assets: paymentUrl: https://payments.payroc.com/merchant/pay-by-link?token=02ada211-ff51-4845-b0b5-e685aeb4b19d paymentButton: | SUPPORT US status: active createdOn: '2024-07-02' - type: singleUse paymentLinkId: CKHP6VVWYT merchantReference: LinkRef7654 order: orderId: OrderRef7654 description: Large Pepperoni Pizza charge: type: preset amount: 4999 currency: USD authType: sale paymentMethods: - card assets: paymentUrl: https://payments.payroc.com/merchant/pay-by-link?token=7c2fc08c-cb0e-44ba-8bcd-cf6de6eb3206 paymentButton: | Pay Now status: active createdOn: '2024-09-24' expiresOn: '2024-10-24' links: - rel: next method: get href: https://api.payroc.com/v1/processing-terminals/1001/payment-links?limit=2&after=CKHP6VVWYT - rel: previous method: get href: https://api.payroc.com/v1/processing-terminals/1001/payment-links?limit=2&before=JZURRJBUPS noActivity: summary: No records found description: Valid request, but no records match the criteria. value: *ref_55 '400': description: Invalid request content: *ref_15 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '404': description: Resource not found content: *ref_18 '406': description: Not acceptable content: *ref_19 '500': description: An error has occured content: *ref_14 /payment-links/{paymentLinkId}: get: tags: - Payment links summary: Retrieve payment link description: | Use this method to retrieve information about a payment link. To retrieve a payment link, you need its paymentLinkId. Our gateway returned the paymentLinkId in the response of the [Create Payment Link](https://docs.payroc.com/api/schema/payment-links/create) method. **Note:** If you don't have the paymentLinkId, use our [List Payment Links](https://docs.payroc.com/api/schema/payment-links/list) method to search for the payment link. Our gateway returns the following information about the payment link: - **type** - Indicates whether the link can be used only once or if it can be used multiple times. - **authType** - Indicates whether the transaction is a sale or a pre-authorization. - **paymentMethods** - Indicates the payment method that the merchant accepts. - **charge** - Indicates whether the merchant or the customer enters the amount for the transaction. - **status** - Indicates if the payment link is active. operationId: retrievePaymentLink parameters: - name: paymentLinkId in: path description: Unique identifier that we assigned to the payment link. required: true schema: &ref_99 type: string minLength: 10 maxLength: 10 examples: &ref_100 example: value: JZURRJBUPS responses: '200': description: "Successful request. We return a polymorphic object that contains payment link information.\nThe value of the type parameter determines which variant you should use:\n-\t`multiUse` - Create a link that the merchant can use to take multiple payments.\n-\t`singleUse` - Create a link that the merchant can use for only one payment.\n" content: application/json: schema: type: object oneOf: - required: *ref_92 type: object title: multiUse description: Object that contains information about a multi-use payment link. properties: *ref_93 - required: *ref_94 type: object title: singleUse description: Object that contains information about a single-use payment link. properties: *ref_95 examples: paymentLink: summary: Payment Link description: Active multi-use payment link. value: *ref_98 '400': description: Invalid request content: *ref_15 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '404': description: Resource not found content: *ref_18 '406': description: Not acceptable content: *ref_19 '500': description: An error has occured content: *ref_14 patch: tags: - Payment links summary: Partially update payment link description: | Use this method to partially update a payment link. Structure your request to follow the [RFC 6902](https://datatracker.ietf.org/doc/html/rfc6902) standard. To update a payment link, you need its paymentLinkId, which we sent you in the response of the [Create Payment Link](https://docs.payroc.com/api/schema/payment-links/create) method. **Note:** If you don't have the paymentLinkId, use our [List Payment Links](https://docs.payroc.com/api/schema/payment-links/list) method to search for the payment link. You can update the following properties of a multi-use link: - **expiresOn parameter** - Expiration date of the link. - **customLabels object** - Label for the payment button. - **credentialOnFile object** - Settings for saving the customer's payment details. You can update the following properties of a single-use link: - **expiresOn parameter** - Expiration date of the link. - **authType parameter** - Transaction type of the payment link. - **amount parameter** - Total amount of the transaction. - **currency parameter** - Currency of the transaction. - **description parameter** - Brief description of the transaction. - **customLabels object** - Label for the payment button. - **credentialOnFile object** - Settings for saving the customer's payment details. **Note:** When a merchant updates a single-use link, we update the payment URL and HTML code in the assets object. The customer can't use the original link to make a payment. operationId: updatePaymentLink parameters: - name: Idempotency-Key in: header required: true 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). schema: *ref_22 examples: *ref_23 - name: paymentLinkId in: path description: Unique identifier that we assigned to the payment link. required: true schema: *ref_99 examples: *ref_100 requestBody: content: application/json: schema: type: array description: A JSON Patch document as defined by RFC 6902. items: *ref_101 example: *ref_102 examples: patchPaymentLinkRealistic: summary: Partially update payment link description: | Partially update an existing payment link. Structure your request to follow the RFC 6902 standard. value: &ref_926 - op: replace path: /expiresOn value: '2024-10-25' patchOperations: summary: Example patch operations that apply the RFC 6902 standard description: | Example patch operations that apply the RFC 6902 standard. value: *ref_103 required: true responses: '200': description: "Successful request. We updated the payment link and return a polymorphic object that contains payment link information.\nThe value of the type parameter determines which variant you should use:\n-\t`multiUse` - Create a link that the merchant can use to take multiple payments.\n-\t`singleUse` - Create a link that the merchant can use for only one payment.\n" content: application/json: schema: type: object oneOf: - required: *ref_92 type: object title: multiUse description: Object that contains information about a multi-use payment link. properties: *ref_93 - required: *ref_94 type: object title: singleUse description: Object that contains information about a single-use payment link. properties: *ref_95 examples: paymentLink: summary: Payment Link description: Active multi-use payment link. value: *ref_98 '400': description: Invalid request content: *ref_15 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '404': description: Resource not found content: *ref_18 '406': description: Not acceptable content: *ref_19 '409': description: Conflict content: *ref_104 '415': description: Unsupported media type content: *ref_105 '500': description: An error has occured content: *ref_14 /payment-links/{paymentLinkId}/deactivate: post: tags: - Payment links summary: Deactivate payment link description: | Use this method to deactivate a payment link. To deactivate a payment link, you need its paymentLinkId. Our gateway returned the paymentLinkId in the response of the [Create Payment Link](https://docs.payroc.com/api/schema/payment-links/create) method. **Note:** If you don't have the paymentLinkId, use our [List Payment Links](https://docs.payroc.com/api/schema/payment-links/list) method to search for the payment link. If your request is successful, our gateway deactivates the payment link. The customer can't use the link to make a payment, and you can't reactivate the payment link. operationId: deactivatePaymentLink parameters: - name: paymentLinkId in: path description: Unique identifier that we assigned to the payment link. required: true schema: *ref_99 examples: *ref_100 responses: '200': description: "Successful request. We return a polymorphic object that contains payment link information. \n\nThe value of the type parameter determines which variant you should use: \n-\t`multiUse` - Create a link that the merchant can use to take multiple payments.\n-\t`singleUse` - Create a link that the merchant can use for only one payment.\n" content: application/json: schema: type: object oneOf: - required: *ref_92 type: object title: multiUse description: Object that contains information about a multi-use payment link. properties: *ref_93 - required: *ref_94 type: object title: singleUse description: Object that contains information about a single-use payment link. properties: *ref_95 examples: deactivatedPaymentLink: summary: Payment link description: Deactivated multi-use payment link. value: &ref_927 type: multiUse paymentLinkId: JZURRJBUPS merchantReference: LinkRef6543 order: description: Pie It Forward charitable trust donation charge: type: prompt currency: USD authType: sale paymentMethods: - card - bankTransfer customLabels: - element: paymentButton label: SUPPORT US assets: paymentUrl: https://payments.payroc.com/merchant/pay-by-link?token=02ada211-ff51-4845-b0b5-e685aeb4b19d paymentButton: | SUPPORT US status: deactivated createdOn: '2024-07-24' '400': description: Invalid request content: *ref_15 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '404': description: Resource not found content: *ref_18 '406': description: Not acceptable content: *ref_19 '409': description: Conflict content: *ref_104 '500': description: An error has occured content: *ref_14 /payment-links/{paymentLinkId}/sharing-events: post: tags: - Payment links summary: Share payment link description: | Use this method to email a payment link to a customer. To email a payment link, you need its paymentLinkId. Our gateway returned the paymentLinkId in the response of the [Create Payment Link](https://docs.payroc.com/api/schema/payment-links/create) method. **Note:** If you don't have the paymentLinkId, use our [List Payment Links](https://docs.payroc.com/api/schema/payment-links/list) method to search for the payment link. In the request, you must provide the recipient's name and email address. In the response, our gateway returns a sharingEventId, which you can use to [List Payment Link Sharing Events](https://docs.payroc.com/api/schema/payment-links/sharing-events/list). operationId: sharePaymentLink parameters: - name: Idempotency-Key in: header required: true 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). schema: *ref_22 examples: *ref_23 - name: paymentLinkId in: path description: Unique identifier that we assigned to the payment link. required: true schema: *ref_99 examples: *ref_100 requestBody: content: application/json: schema: type: object description: Polymorphic object that contains information about how to share a payment link. oneOf: - required: &ref_106 - sharingMethod - recipients type: object title: email description: Object that contains the information about a sharing event that the merchant sent by email. properties: &ref_107 sharingMethod: type: string description: Method that the merchant uses to share the payment link. enum: - email example: email sharingEventId: maxLength: 10 minLength: 10 type: string readOnly: true description: Unique identifier that we assigned to the sharing event. example: GTZH5WVXK9 dateTime: type: string readOnly: true format: date-time description: Date and time that the merchant shared the link. Our gateway returns this value in the [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format. example: '2024-07-02T15:30:00Z' merchantCopy: type: boolean default: false writeOnly: true description: Indicates if we send a copy of the email to the merchant. By default, we don't send a copy to the merchant. example: true message: type: string description: Message that the merchant sends with the payment link. maxLength: 1024 example: | Dear Sarah, Your insurance is expiring this month. Please pay the renewal fee by the end of the month to renew your insurance. recipients: type: array uniqueItems: true description: Array that contains the recipients of the payment link. items: required: &ref_627 - name - email type: object description: Object that contains the contact details of the recipient. properties: &ref_628 name: maxLength: 48 minLength: 1 type: string description: Recipient's name. example: Sarah Hazel Hopper email: maxLength: 128 minLength: 6 type: string description: Recipient's email address. example: sarah.hopper@example.com examples: sharePaymentLinkRequest: summary: Share a payment link. description: Share a payment link. value: &ref_929 sharingMethod: email merchantCopy: true message: | Dear Sarah, Your insurance is expiring this month. Please, pay the renewal fee by the end of the month to renew it. recipients: - name: Sarah Hazel Hopper email: sarah.hopper@example.com responses: '201': description: Successful request. We return a polymorphic object that contains information about how the merchant shared a payment link. content: application/json: schema: type: object oneOf: - required: *ref_106 type: object title: email description: Object that contains the information about a sharing event that the merchant sent by email. properties: *ref_107 examples: paymentLinkShareEvent: summary: Payment link sharing event. description: Payment link sharing event value: &ref_930 sharingMethod: email sharingEventId: GTZH5WVXK9 dateTime: '2024-07-02T15:30:00Z' message: | Dear Sarah, You can pay for your order via the link below. recipients: - name: Sarah Hazel Hopper email: sarah.hopper@example.com '400': description: Invalid request content: *ref_15 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '404': description: Resource not found content: *ref_18 '406': description: Not acceptable content: *ref_19 '409': description: Conflict content: *ref_104 '415': description: Unsupported media type content: *ref_105 '500': description: An error has occured content: *ref_14 get: tags: - Payment links summary: List payment link sharing events description: | Use this method to return a [paginated](https://docs.payroc.com/api/pagination) list of sharing events for a payment link. A sharing event occurs when a merchant shares a payment link with a customer. To list the sharing events for a payment link, you need its paymentLinkId. Our gateway returned the paymentLinkId in the response of the [Create Payment Link](https://docs.payroc.com/api/schema/payment-links/create) method. **Note:** If you don't have the paymentLinkId, use our [List Payment Links](https://docs.payroc.com/api/schema/payment-links/list) method to search for the payment link. Use query parameters to filter the list of results that we return, for example, to search for links sent to a specific customer. Our gateway returns the following information for each sharing event in the list: - Customer that the merchant sent the link to. - Date that the merchant sent the link. operationId: listPaymentLinkShareEvents parameters: - name: paymentLinkId in: path description: Unique identifier that we assigned to the payment link. required: true schema: *ref_99 examples: *ref_100 - name: recipientName in: query description: Filter results by the customer's name. schema: *ref_108 examples: *ref_109 - name: recipientEmail in: query description: Filter results by the customer's email address. schema: *ref_110 examples: *ref_111 - name: before in: query description: | Return the previous page of results before the value that you specify. You can’t send the before parameter in the same request as the after parameter. schema: *ref_32 examples: *ref_33 - name: after in: query description: | Return the next page of results after the value that you specify. You can’t send the after parameter in the same request as the before parameter. schema: *ref_34 examples: *ref_35 - name: limit in: query description: Limit the maximum number of results that we return for each page. schema: *ref_36 examples: *ref_37 responses: '200': description: Successful request. Returns a [paginated](https://docs.payroc.com/api/pagination) list of sharing events for the payment link. content: application/json: schema: required: &ref_629 - count - data - hasMore - limit type: object allOf: &ref_630 - type: object description: Contains the pagination properties that you use to navigate through a list of results. properties: *ref_38 - type: object properties: data: type: array description: Array of polymorphic objects that contain information about how the merchant shared a payment link. items: type: object oneOf: - required: *ref_106 type: object title: email description: Object that contains the information about a sharing event that the merchant sent by email. properties: *ref_107 examples: paginatedResults: summary: Sharing events description: Paginated list of payment link sharing events value: &ref_928 limit: 2 count: 2 hasMore: true data: - sharingMethod: email sharingEventId: GKB49GZ6DL dateTime: '2024-07-02T15:30:00Z' message: | Dear Sarah, You can pay for your order via the link below. recipients: - name: Sarah Hazel Hopper email: sarah.hopper@example.com - sharingMethod: email sharingEventId: GTZH5WVXK9 dateTime: '2024-07-02T15:30:00Z' message: | Dear Sarah, Thank you for continuing to support our Pie It Forward charitable trust. You can make your payment via the link below. recipients: - name: Sarah Hazel Hopper email: sarah.hopper@example.com links: - rel: next method: get href: https://api.payroc.com/v1/payment-links/CKHP6VVWYT/sharing-events?limit=2&after=GTZH5WVXK9 - rel: previous method: get href: https://api.payroc.com/v1/payment-links/CKHP6VVWYT/sharing-events?limit=2&before=GKB49GZ6DL noActivity: summary: No records found description: Valid request, but no records match the criteria. value: *ref_55 '400': description: Invalid request content: *ref_15 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '404': description: Resource not found content: *ref_18 '406': description: Not acceptable content: *ref_19 '500': description: An error has occured content: *ref_14 /processing-terminals/{processingTerminalId}/payment-plans: post: tags: - Payment plans summary: Create payment plan description: "Use this method to create a payment schedule that you can assign customers to. \n\n**Note:** This method is part of our Repeat Payments feature. To help you understand how this method works with our Subscriptions endpoints, go to [Repeat Payments](https://docs.payroc.com/guides/take-payments/repeat-payments). \n\nWhen you create a payment plan you need to provide a unique paymentPlanId that you use to run follow-on actions: \n\n-\t[Retrieve Payment Plan](https://docs.payroc.com/api/schema/repeat-payments/payment-plans/retrieve) - View the details of the payment plan. \n-\t[Update Payment Plan](https://docs.payroc.com/api/schema/repeat-payments/payment-plans/partially-update) - Update the details of the payment plan. \n-\t[Delete Payment Plan](https://docs.payroc.com/api/schema/repeat-payments/payment-plans/delete) - Delete the payment plan. \n-\t[Create Subscription](https://docs.payroc.com/api/schema/repeat-payments/subscriptions/create) - Subscribe a customer to the payment plan. \n\nThe request includes the following settings: \n\n-\t**type** - Indicates if our gateway or the merchant collects payments. If the merchant manually collects payments, integrate with the [Pay Manual Subscription](https://docs.payroc.com/api/schema/repeat-payments/subscriptions/pay) method. \n-\t**recurringOrder** - Amount of each payment if the gateway automatically collect payments. \n-\t**setupOrder** - Setup fee that our gateway immediately collects from the customer's payment method. \n-\t**onUpdate and onDelete** - Indicates what happens to associated subscriptions if the merchant updates or deletes the payment plan. \n" operationId: createPaymentPlan parameters: - name: Idempotency-Key in: header required: true 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). schema: *ref_22 examples: *ref_23 - name: processingTerminalId in: path required: true description: Unique identifier that we assigned to the terminal. schema: *ref_96 examples: *ref_97 requestBody: content: application/json: schema: required: &ref_114 - paymentPlanId - name - currency - frequency - onDelete - onUpdate - type type: object allOf: &ref_115 - required: &ref_631 - paymentPlanId - name - currency - frequency - onDelete - onUpdate - type type: object properties: &ref_632 paymentPlanId: maxLength: 48 minLength: 1 type: string description: Unique identifier that the merchant assigns to the payment plan. example: PlanRef8765 processingTerminalId: maxLength: 50 minLength: 4 type: string readOnly: true description: Unique identifier of the terminal that the payment plan is assigned to. example: '1234001' name: maxLength: 128 minLength: 5 type: string description: Name of the payment plan. example: Premium Club description: maxLength: 128 minLength: 0 type: string description: Description of the payment plan. example: Monthly Premium Club subscription currency: type: string description: Currency of the transaction. The value for the currency follows the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard. enum: *ref_83 length: minimum: 0 default: 0 type: integer format: int32 description: | Number of payments for the payment plan. To indicate that the payment plan should run indefinitely, send a value of `0`. example: 12 type: type: string default: automatic description: | Indicates how the merchant takes the payment from the customer's account. - `manual` - The merchant manually collects payments from the customer. - `automatic` - The terminal automatically collects payments from the customer. enum: - manual - automatic example: automatic frequency: type: string description: Indicates how often the merchant or the terminal collects a payment from the customer. enum: - weekly - fortnightly - monthly - quarterly - yearly example: monthly onUpdate: type: string default: continue description: | Indicates whether any changes that the merchant makes to the payment plan apply to existing subscriptions. - `update` - Changes apply to existing subscriptions. - `continue` - Changes don't apply to existing subscriptions. enum: - update - continue example: continue onDelete: type: string default: complete description: | Indicates what happens to existing subscriptions if the merchant deletes the payment plan. - `complete` - Stops existing subscriptions. - `continue` - Continues existing subscriptions. enum: - complete - continue example: continue customFieldNames: type: array description: | Array of custom fields that you can use in subscriptions linked to the payment plan. items: maxLength: 56 minLength: 1 type: string example: - yourCustomField - type: object properties: setupOrder: type: object allOf: &ref_636 - type: object description: Object that contains information about the initial cost that a customer pays to set up the subscription. properties: &ref_633 amount: type: integer format: int64 exclusiveMinimum: 0 maximum: 999999999999 description: Total amount before surcharges. The value is in the currency's lowest denomination, for example, cents. example: 4999 description: maxLength: 1024 minLength: 1 type: string description: Description of the transaction. example: Initial setup fee for Premium Club subscription - type: object properties: breakdown: required: &ref_112 - subtotal type: object allOf: &ref_113 - required: &ref_634 - subtotal type: object description: | Object that contains information about the taxes that apply to the transaction. properties: &ref_635 subtotal: type: integer format: int64 description: Total amount for the transaction before tax. The value is in the currency's lowest denomination, for example, cents. example: 4999 - type: object properties: taxes: type: array description: Array of tax objects. items: required: &ref_124 - name - rate type: object properties: &ref_125 name: type: string description: Name of the tax. maxLength: 64 minLength: 1 example: Sales Tax rate: type: number format: double description: Tax percentage for the transaction. maximum: 99.99999 minimum: 0 example: 7 amount: type: integer format: int64 readOnly: true description: Amount of tax that was applied to the transaction. The value is in the currency's lowest denomination, for example, cents. exclusiveMinimum: 0 example: 190 recurringOrder: type: object allOf: &ref_638 - type: object description: | Object that contains information about the cost of each payment. **Note:** Send this object only if the value for **type** is `automatic`. properties: &ref_637 amount: type: integer format: int64 description: Total amount before surcharges. The value is in the currency's lowest denomination, for example, cents. example: 4999 description: maxLength: 1024 minLength: 1 type: string description: Description of the transaction. example: Monthly Premium Club subscription - type: object properties: breakdown: required: *ref_112 type: object allOf: *ref_113 examples: paymentPlanRequest: summary: Payment Plan description: Payment Plan value: &ref_932 paymentPlanId: PlanRef8765 name: Premium Club description: Monthly Premium Club subscription currency: USD setupOrder: amount: 4999 description: Initial setup fee for Premium Club subscription breakdown: subtotal: 4347 taxes: - type: rate name: Sales Tax rate: 5 recurringOrder: amount: 4999 description: Monthly Premium Club subscription breakdown: subtotal: 4347 taxes: - type: rate name: Sales Tax rate: 5 length: 12 type: automatic frequency: monthly onUpdate: continue onDelete: complete customFieldNames: - yourCustomField required: true responses: '201': description: Successful request. We created the payment plan. content: application/json: schema: required: *ref_114 type: object allOf: *ref_115 examples: createdPaymentPlan: summary: Payment Plan description: Payment Plan value: &ref_116 paymentPlanId: PlanRef8765 processingTerminalId: '1234001' name: Premium Club description: Monthly Premium Club subscription currency: USD setupOrder: amount: 4999 description: Initial setup fee for Premium Club subscription breakdown: subtotal: 4347 taxes: - name: Sales Tax rate: 5 recurringOrder: amount: 4999 description: Monthly Premium Club subscription breakdown: subtotal: 4347 taxes: - name: Sales Tax rate: 5 length: 12 type: automatic frequency: monthly onUpdate: continue onDelete: complete customFieldNames: - yourCustomField headers: location: description: URI reference to created resource. schema: *ref_24 examples: *ref_25 '400': description: Validation error content: application/problem+json: schema: type: object properties: *ref_9 required: *ref_10 examples: validationError: summary: Bad Request description: One or more validation errors occurred value: *ref_11 idempotentKeyMissing: summary: Idempotency key missing description: Idempotency key must be supplied value: *ref_26 idempotentKeyInUse: summary: Idempotency key in use description: Idempotency key in use value: *ref_29 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '406': description: Not acceptable content: *ref_19 '409': description: Conflict content: *ref_104 '415': description: Unsupported media type content: *ref_105 '500': description: An error has occured content: *ref_14 get: tags: - Payment plans summary: List payment plans description: "Use this method to return a [paginated](https://docs.payroc.com/api/pagination) list of payment plans for a processing terminal. \n\n**Note:** If you want to view the details of a specific payment plan and you have its paymentPlanId, use our [Retrieve Payment Plan](https://docs.payroc.com/api/schema/repeat-payments/payment-plans/retrieve) method. \n\nOur gateway returns the following information about each payment plan in the list: \n\n -\tName, length, and currency of the plan \n -\tHow often our gateway collects each payment \n -\tHow much our gateway collects for each payment \n -\tWhat happens if the merchant updates or deletes the plan \n\nFor each payment plan, we return the paymentPlanId, which you can use to perform follow-on actions.\n" operationId: listPaymentPlans parameters: - name: processingTerminalId in: path required: true description: Unique identifier that we assigned to the terminal. schema: *ref_96 examples: *ref_97 - name: before in: query description: | Return the previous page of results before the value that you specify. You can’t send the before parameter in the same request as the after parameter. schema: *ref_32 examples: *ref_33 - name: after in: query description: | Return the next page of results after the value that you specify. You can’t send the after parameter in the same request as the before parameter. schema: *ref_34 examples: *ref_35 - name: limit in: query description: Limit the maximum number of results that we return for each page. schema: *ref_36 examples: *ref_37 responses: '200': description: Successful request. Returns a paginated list of payment plans. content: application/json: schema: required: &ref_639 - count - data - hasMore - limit type: object allOf: &ref_640 - type: object description: Contains the pagination properties that you use to navigate through a list of results. properties: *ref_38 - type: object properties: data: type: array description: Array of paymentPlan objects. items: required: *ref_114 type: object allOf: *ref_115 examples: paginatedResults: summary: Payment Plan description: Payment Plan value: &ref_931 limit: 2 count: 2 hasMore: true data: - paymentPlanId: PlanRef8765 processingTerminalId: '1234001' name: Premium Club description: Monthly Premium Club subscription currency: USD length: 12 type: automatic frequency: monthly onUpdate: continue onDelete: complete - paymentPlanId: PlanRef8766 processingTerminalId: '1234001' name: Pie It Forward description: Pie It Forward charitable trust donation currency: USD length: 0 type: automatic frequency: yearly onUpdate: continue onDelete: complete customFieldNames: - yourCustomField links: - rel: next method: get href: https://api.payroc.com/v1/processing-terminals/1001/payment-plans?limit=2&after=PlanRef8766 - rel: previous method: get href: https://api.payroc.com/v1/processing-terminals/1001/payment-plans?limit=2&before=PlanRef8765 noActivity: summary: No records found description: Valid request, but no records match the criteria. value: *ref_55 '400': description: Invalid request content: *ref_15 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '406': description: Not acceptable content: *ref_19 '500': description: An error has occured content: *ref_14 /processing-terminals/{processingTerminalId}/payment-plans/{paymentPlanId}: get: tags: - Payment plans summary: Retrieve payment plan description: "Use this method to retrieve information about a payment plan. \n\nTo retrieve a payment plan, you need its paymentPlanId. Our gateway returned the paymentPlanId in the response of the [Create Payment Plan](https://docs.payroc.com/api/schema/repeat-payments/payment-plans/create) method. \n\n**Note:** If you don't have the paymentPlanId, use our [List Payment Plans](https://docs.payroc.com/api/schema/repeat-payments/payment-plans/list) method to search for the payment plan. \n\nOur gateway returns the following information about the payment plan: \n\n -\tName, length, and currency of the plan \n -\tHow often our gateway collects each payment \n -\tHow much our gateway collects for each payment \n -\tWhat happens if the merchant updates or deletes the plan \n" operationId: getPaymentPlan parameters: - name: processingTerminalId in: path required: true description: Unique identifier that we assigned to the terminal. schema: *ref_96 examples: *ref_97 - name: paymentPlanId in: path description: Unique identifier that the merchant assigned to the payment plan. required: true schema: &ref_117 maxLength: 48 minLength: 1 type: string examples: &ref_118 example: value: PlanRef8765 responses: '200': description: Successful request. Returns the requested payment plan. content: application/json: schema: required: *ref_114 type: object allOf: *ref_115 examples: paymentPlan: summary: Payment Plan description: Payment Plan value: *ref_116 '400': description: Invalid request content: *ref_15 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '404': description: Resource not found content: *ref_18 '406': description: Not acceptable content: *ref_19 '500': description: An error has occured content: *ref_14 patch: tags: - Payment plans summary: Partially update payment plan description: | Use this method to partially update a payment plan. Structure your request to follow the [RFC 6902](https://datatracker.ietf.org/doc/html/rfc6902) standard. To update a payment plan, you need its paymentPlanId, which you sent in the request of the [Create Payment Plan](https://docs.payroc.com/api/schema/repeat-payments/payment-plans/create) method. **Note:** If you don't have the paymentPlanId, use our [List Payment Plans](https://docs.payroc.com/api/schema/repeat-payments/payment-plans/list) method to search for the payment plan. You can update all of the properties of the payment plan except for the paymentPlanId. The value you sent for the onUpdate parameter when you created the payment plan indicates what happens to the associated subscriptions when you update the plan: - `update` - Our gateway updates the subscriptions associated with the payment plan. - `continue` - Our gateway doesn't update the subscriptions associated with the payment plan. operationId: updatePaymentPlan parameters: - name: Idempotency-Key in: header required: true 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). schema: *ref_22 examples: *ref_23 - name: processingTerminalId in: path required: true description: Unique identifier that we assigned to the terminal. schema: *ref_96 examples: *ref_97 - name: paymentPlanId in: path description: Unique identifier that the merchant assigned to the payment plan. required: true schema: *ref_117 examples: *ref_118 requestBody: content: application/json: schema: type: array description: A JSON Patch document as defined by RFC 6902. items: *ref_101 example: *ref_102 examples: patchPaymentPlanRealistic: summary: Update payment plan description: | Make changes to an existing payment plan. Structure your request to follow the [RFC 6902](https://datatracker.ietf.org/doc/html/rfc6902) standard. value: &ref_933 - op: replace path: /currency value: USD - op: replace path: /setupOrder/amount value: 2999 - op: replace path: /frequency value: yearly patchOperations: summary: Example patch operations that apply the RFC 6902 standard description: | Example patch operations that apply the RFC 6902 standard. value: *ref_103 required: true responses: '200': description: Successful request. We updated the payment plan. content: application/json: schema: required: *ref_114 type: object allOf: *ref_115 examples: paymentPlan: summary: Payment Plan description: Payment Plan value: *ref_116 '400': description: Invalid request content: *ref_15 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '404': description: Resource not found content: *ref_18 '406': description: Not acceptable content: *ref_19 '409': description: Conflict content: *ref_104 '415': description: Unsupported media type content: *ref_105 '500': description: An error has occured content: *ref_14 delete: tags: - Payment plans summary: Delete payment plan description: "Use this method to delete a payment plan. \n\n> **Important:** When you delete a payment plan, you can’t recover it. You also won’t be able to add subscriptions to the payment plan. \n\nTo delete a payment plan, you need its paymentPlanId, which you sent in the request of the [Create Payment Plan](https://docs.payroc.com/api/schema/repeat-payments/payment-plans/create) method. \n\n**Note:** If you don't have the paymentPlanId, use our [List Payment Plans](https://docs.payroc.com/api/schema/repeat-payments/payment-plans/list) method to search for the payment plan. \n\nThe value you sent for the onDelete parameter when you created the payment plan indicates what happens to associated subscriptions when you delete the plan: \n\n -\t`complete` - Our gateway stops taking payments for the subscriptions associated with the payment plan. \n -\t`continue` - Our gateway continues to take payments for the subscriptions associated with the payment plan. To stop a subscription for a cancelled payment plan, go to the [Deactivate Subscription](https://docs.payroc.com/api/schema/repeat-payments/subscriptions/deactivate) method. \n" operationId: deletePaymentPlan parameters: - name: processingTerminalId in: path required: true description: Unique identifier that we assigned to the terminal. schema: *ref_96 examples: *ref_97 - name: paymentPlanId in: path description: Unique identifier that the merchant assigned to the payment plan. required: true schema: *ref_117 examples: *ref_118 responses: '204': description: Successful request. We deleted the payment plan. '400': description: Invalid request content: *ref_15 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '404': description: Resource not found content: *ref_18 '500': description: An error has occured content: *ref_14 /processing-terminals/{processingTerminalId}/subscriptions: post: tags: - Subscriptions summary: Create subscription description: | Use this method to assign a customer to a payment plan. **Note:** This method is part of our Repeat Payments feature. To help you understand how this method works with our Payment plans endpoints, go to [Repeat Payments](https://docs.payroc.com/guides/take-payments/repeat-payments). When you create a subscription you need to provide a unique subscriptionId that you use to run follow-on actions: - [Retrieve Subscription](https://docs.payroc.com/api/schema/repeat-payments/subscriptions/retrieve) - View the details of the subscription. - [Update Subscription](https://docs.payroc.com/api/schema/repeat-payments/subscriptions/partially-update) - Update the details of the subscription. - [Deactivate Subscription](https://docs.payroc.com/api/schema/repeat-payments/subscriptions/deactivate) - Stop taking payments for the subscription. - [Re-activate Subscription](https://docs.payroc.com/api/schema/payments/subscriptions/reactivate) - Start taking payments again for the subscription. - [Pay Manual Subscription](https://docs.payroc.com/api/schema/repeat-payments/subscriptions/pay) - Manually collect a payment for the subscription. The request includes the following settings: - **paymentPlanId** - Unique identifier of the payment plan that the merchant wants to use. If you don't have the paymentPlanId, use our [List Payment Plans](https://docs.payroc.com/api/schema/repeat-payments/payment-plans/list) method to search for the payment plan. - **paymentMethod** - Object that contains information about the secure token, which represents the customer's card details or bank account details. - **startDate** - Date that you want to start to take payments. You can also update the settings that the subscription inherited from the payment plan, for example, you can change the amount for each payment. If you change the settings for the subscription, it doesn't change the settings in the payment plan that it's linked to. operationId: createSubscription parameters: - name: Idempotency-Key in: header required: true 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). schema: *ref_22 examples: *ref_23 - name: processingTerminalId in: path required: true description: Unique identifier that we assigned to the terminal. schema: *ref_96 examples: *ref_97 requestBody: content: application/json: schema: required: &ref_648 - paymentMethod - paymentPlanId - startDate - subscriptionId type: object properties: &ref_649 subscriptionId: maxLength: 48 minLength: 1 type: string description: Unique identifier that the merchant assigned to the subscription. example: SubRef7654 paymentPlanId: maxLength: 48 minLength: 1 type: string description: Unique identifier that the merchant assigned to the payment plan. example: PlanRef8765 paymentMethod: type: object description: Polymorphic object that contains information about the secure token. discriminator: propertyName: type mapping: secureToken: '#/components/schemas/secureTokenPayload' oneOf: - required: &ref_179 - type - token type: object writeOnly: true title: secureToken description: Object that contains information about the secure token that represents the customer’s payment details. properties: &ref_180 type: type: string description: Method that the terminal used to take the payment. enum: - secureToken example: secureToken accountType: type: string description: | Indicates the customer’s account type. **Note:** Send a value for accountType only if the secure token represents bank account details. enum: - checking - savings example: checking token: maxLength: 19 minLength: 12 type: string description: Unique token that the gateway assigned to the payment details. example: '1234567890123456789' secCode: type: string description: | Indicates how the customer authorized the ACH transaction. Send one of the following values: - `web` – Online transaction. - `tel` – Telephone transaction. - `ccd` – Corporate credit card or debit card transaction. - `ppd` – Pre-arranged transaction. enum: - web - tel - ccd - ppd example: web name: maxLength: 128 minLength: 5 type: string description: | Name of the subscription. This value replaces the name inherited from the payment plan. example: Premium Club description: maxLength: 128 minLength: 1 type: string description: | Description of the subscription. This value replaces the description inherited from the payment plan. example: Monthly Premium Club subscription. Two large pizzas free per month, and exclusive member discounts. setupOrder: type: object allOf: &ref_646 - description: Object that contains information about the initial cost that a customer pays to set up the subscription. type: object properties: &ref_121 orderId: maxLength: 24 minLength: 1 type: string description: A unique identifier assigned by the merchant. example: OrderRef6543 amount: type: integer format: int64 exclusiveMinimum: 0 maximum: 999999999999 description: | Total amount for the transaction. The value is in the currency's lowest denomination, for example, cents.

**Important:** Do not add the surcharge to the amount parameter in the request. If the transaction is eligible for surcharging, our gateway adds the surcharge to the amount in the request, and then returns the updated amount in the response. example: 4999 description: maxLength: 1024 minLength: 1 type: string description: Description of the transaction. example: Monthly Premium Club subscription - type: object properties: breakdown: required: &ref_119 - subtotal type: object description: | Object that contains information about the taxes to apply to the transaction. allOf: &ref_120 - required: &ref_122 - subtotal type: object properties: &ref_123 subtotal: type: integer format: int64 description: Total amount for the transaction before tax. The value is in the currency's lowest denomination, for example, cents. example: 4500 convenienceFee: required: &ref_172 - amount type: object readOnly: true description: Object that contains information about the convenience fee for the transaction. properties: &ref_173 amount: exclusiveMinimum: 0 type: integer format: int64 description: | If the merchant added a convenience fee, this value indicates the amount of the convenience fee in the currency’s lowest denomination, for example, cents. example: 25 - type: object properties: taxes: type: array description: Array of tax objects. items: type: object required: &ref_170 - name - rate - type properties: &ref_171 type: type: string enum: - rate default: rate description: Indicates that the tax is a rate. rate: type: number format: double description: Tax percentage for the transaction. maximum: 99.99999 minimum: 0 example: 7 name: type: string description: Name of the tax. A tax validation on the stored rate for the tax name is performed. maxLength: 64 minLength: 1 example: Sales Tax recurringOrder: type: object description: | Object that contains information about the cost of each payment. **Note:** Send this object only if the value for **type** is `automatic`. allOf: &ref_647 - type: object properties: &ref_126 amount: type: integer format: int64 description: | Total amount for the transaction. The value is in the currency's lowest denomination, for example, cents.

**Important:** Do not add the surcharge to the amount parameter in the request. If the transaction is eligible for surcharging, our gateway adds the surcharge to the amount in the request, and then returns the updated amount in the response. example: 4999 description: maxLength: 1024 minLength: 1 type: string description: Description of the transaction. example: Monthly Premium Club subscription - type: object properties: breakdown: required: *ref_119 type: object description: | Object that contains information about the taxes to apply to the transaction. allOf: *ref_120 startDate: type: string format: date description: | Format: **YYYY-MM-DD** Subscription's start date. example: '2024-05-02' endDate: type: string format: date description: | Format: **YYYY-MM-DD** Subscription's end date. **Note:** If you provide values for both **length** and **endDate**, our gateway uses the value for **endDate** to determine when the subscription should end. example: '2025-05-02' length: minimum: 0 type: integer format: int32 description: | Total number of billing cycles. To indicate that the subscription should run indefinitely, send a value of `0`. This value replaces the **length** inherited from the payment plan. **Note:** If you provide values for both **length** and **endDate**, our gateway uses the value for **endDate** to determine when the subscription should end. example: 12 pauseCollectionFor: type: integer format: int32 description: | Number of billing cycles that the merchant wants to pause payments for. For example, if the merchant wants to offer a free trial period. example: 0 customFields: type: array description: | Array of customField objects. items: required: &ref_129 - name - value type: object properties: &ref_130 name: maxLength: 56 minLength: 1 type: string description: Name of the custom field. example: yourCustomField value: maxLength: 100 minLength: 1 type: string description: Value for the custom field. example: abc123 examples: createSubscription: summary: Subscription description: Subscription value: &ref_935 subscriptionId: SubRef7654 paymentPlanId: PlanRef8765 paymentMethod: type: secureToken token: '296753123456' name: Premium Club description: Premium Club subscription setupOrder: amount: 4999 description: Initial setup fee for Premium Club subscription orderId: OrderRef6543 recurringOrder: amount: 4999 description: Monthly Premium Club subscription breakdown: subtotal: 4347 taxes: - type: rate name: Sales Tax rate: 5 startDate: '2024-07-02' endDate: '2025-07-01' length: 12 pauseCollectionFor: 0 required: true responses: '201': description: Successful request. We created the subscription. content: application/json: schema: required: &ref_131 - subscriptionId - processingTerminalId - paymentPlan - secureToken - name - currency - currentState - startDate - type - frequency type: object properties: &ref_132 subscriptionId: maxLength: 48 minLength: 1 type: string description: Unique identifier that the merchant assigned to the subscription. example: SubRef7654 processingTerminalId: maxLength: 50 minLength: 4 type: string description: Unique identifier of the terminal that the subscription is linked to. example: '1234001' paymentPlan: required: &ref_641 - name - paymentPlanId type: object properties: &ref_642 paymentPlanId: maxLength: 48 minLength: 1 type: string description: Unique identifier that the merchant assigns to the payment plan. example: PlanRef8765 name: maxLength: 128 minLength: 5 type: string description: Name of the payment plan. example: Monthly Premium Club subscription link: type: object readOnly: true description: Object that contains HATEOAS links for the resource. properties: *ref_4 required: *ref_5 example: *ref_6 secureToken: required: &ref_138 - customerName - secureTokenId - status - token type: object description: Object that contains information about the secure token. properties: &ref_139 secureTokenId: maxLength: 200 minLength: 1 type: string description: Unique identifier that the merchant assigned to the secure token. example: MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa customerName: maxLength: 50 minLength: 1 type: string description: Customer's name. example: Sarah Hazel Hopper token: maxLength: 19 minLength: 12 type: string description: | Token that the merchant can use in future transactions to represent the customer's payment details. The token: - Begins with the six-digit identification number **296753**. - Contains up to 12 digits. - Contains a single check digit that we calculate using the Luhn algorithm. example: '296753123456' status: type: string 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. enum: - notValidated - cvvValidated - validationFailed - issueNumberValidated - cardNumberValidated - bankAccountValidated example: cvvValidated link: type: object readOnly: true description: Object that contains HATEOAS links for the resource. properties: *ref_4 required: *ref_5 example: *ref_6 name: maxLength: 128 minLength: 5 type: string description: Name of the subscription. example: Premium Club description: maxLength: 128 minLength: 1 type: string description: Description of the subscription. example: Monthly Premium Club subscription. Two large pizzas free per month, and exclusive member discounts. currency: type: string description: Currency of the transaction. The value for the currency follows the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard. enum: *ref_83 setupOrder: type: object allOf: &ref_137 - description: Object that contains information about the initial cost that a customer pays to set up the subscription. type: object properties: *ref_121 - type: object properties: breakdown: required: &ref_127 - subtotal type: object description: | Object that contains information about the surcharge and taxes that apply to the transaction. allOf: &ref_128 - required: *ref_122 type: object properties: *ref_123 - type: object properties: surcharge: description: Object that contains information about the [surcharge](https://docs.payroc.com/knowledge/card-payments/credit-card-surcharging) that we applied to the transaction. allOf: - type: object description: | Object that contains information about the surcharge. properties: &ref_169 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. example: false amount: exclusiveMinimum: 0 type: integer format: int64 readOnly: true 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. example: 50 percentage: maximum: 100 exclusiveMinimum: 0 type: number format: double readOnly: true description: If the merchant added a surcharge fee, this value indicates the surcharge percentage. example: 2 taxes: type: array description: Array of tax objects. items: required: *ref_124 type: object properties: *ref_125 recurringOrder: type: object description: | Object that contains information about the cost of each payment. allOf: &ref_643 - type: object properties: *ref_126 - type: object properties: breakdown: required: *ref_127 type: object description: | Object that contains information about the surcharge and taxes that apply to the transaction. allOf: *ref_128 currentState: required: &ref_140 - paidInvoices - status type: object description: A snapshot of the subscription's current state. properties: &ref_141 status: type: string description: | Status of the Subscription. - 'active' - Subscription is active. - 'completed' - Subscription has reached the end date or the total number of billing cycles. - 'cancelled' - Merchant deactivated the subscription. - 'suspended' - Subscription is suspended. For example, if the customer misses payments. enum: - active - completed - suspended - cancelled example: active nextDueDate: type: string description: Date that the merchant collects the next payment. format: date example: '2024-08-02' paidInvoices: minimum: 0 type: integer description: Number of payments that the merchant has collected. format: int32 example: 3 outstandingInvoices: minimum: 0 type: integer description: | Number of payments until the end of the subscription. Our gateway returns a value for **outstandingInvoices** only if the subscription has an end date or a fixed number of billing cycles. format: int32 example: 9 startDate: type: string format: date description: | Format: **YYYY-MM-DD** Subscription's start date. example: '2024-05-02' endDate: type: string format: date description: | Format: **YYYY-MM-DD** Subscription's end date. **Note:** If you provide values for both **length** and **endDate**, our gateway uses the value for **endDate** to determine when the subscription should end. example: '2025-05-02' length: minimum: 0 type: integer format: int32 description: | Total number of billing cycles. To indicate that the subscription should run indefinitely, send a value of `0`. This value replaces the **length** inherited from the payment plan. **Note:** If you provide values for both **length** and **endDate**, our gateway uses the value for **endDate** to determine when the subscription should end. example: 12 type: type: string description: | How the merchant takes the payment from the customer’s account. - `manual` – The merchant manually collects payments from the customer. - `automatic` – The terminal automatically collects payments from the customer. enum: - manual - automatic example: automatic frequency: type: string description: Indicates how often the merchant or the terminal collects a payment from the customer. enum: - weekly - fortnightly - monthly - quarterly - yearly example: monthly pauseCollectionFor: minimum: 0 type: integer format: int32 description: | Number of billing cycles that the merchant wants to pause payments for. For example, if the merchant wants to offer a free trial period. example: 0 customFields: type: array description: | Array of customField objects. items: required: *ref_129 type: object properties: *ref_130 examples: createdSubscriptionWithSurcharge: summary: Subscription with surcharge description: Subscription with surcharge value: &ref_133 subscriptionId: SubRef7654 processingTerminalId: '1234001' paymentPlan: paymentPlanId: PlanRef8765 name: Monthly Premium Club subscription link: rel: self method: GET href: https://api.payroc.com/v1/processing-terminals/1234001/payment-plans/PlanRef8765 secureToken: secureTokenId: MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa customerName: Sarah Hazel Hopper token: '296753123456' status: notValidated link: rel: self method: GET href: https://api.payroc.com/v1/processing-terminals/1234001/secure-tokens/MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa name: Premium Club description: Premium Club subscription currency: USD setupOrder: orderId: OrderRef6543 amount: 4999 description: Initial setup fee for Premium Club subscription breakdown: subtotal: 4347 taxes: - name: Sales Tax rate: 5 surcharge: amount: 217 percentage: 5 recurringOrder: amount: 4999 description: Premium Club subscription breakdown: subtotal: 4347 taxes: - name: Sales Tax rate: 5 surcharge: amount: 217 percentage: 5 currentState: status: active nextDueDate: '2024-08-02' paidInvoices: 0 outstandingInvoices: 3 startDate: '2024-07-02' endDate: '2025-07-01' length: 12 type: automatic frequency: monthly pauseCollectionFor: 0 customFields: - name: yourCustomField value: abc123 createdSubscriptionWithConvenienceFee: summary: Subscription with convenience fee description: Subscription with convenience fee value: &ref_134 subscriptionId: SubRef7654 processingTerminalId: '1234001' paymentPlan: paymentPlanId: PlanRef8765 name: Monthly Premium Club subscription link: rel: self method: GET href: https://api.payroc.com/v1/processing-terminals/1234001/payment-plans/PlanRef8765 secureToken: secureTokenId: MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa customerName: Sarah Hazel Hopper token: '296753123456' status: notValidated link: rel: self method: GET href: https://api.payroc.com/v1/processing-terminals/1234001/secure-tokens/MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa name: Premium Club description: Premium Club subscription currency: USD setupOrder: orderId: OrderRef6543 amount: 4999 description: Initial setup fee for Premium Club subscription breakdown: subtotal: 4347 taxes: - name: Sales Tax rate: 5 convenienceFee: amount: 217 recurringOrder: amount: 4999 description: Premium Club subscription breakdown: subtotal: 4347 taxes: - name: Sales Tax rate: 5 convenienceFee: amount: 217 currentState: status: active nextDueDate: '2024-08-02' paidInvoices: 0 outstandingInvoices: 3 startDate: '2024-07-02' endDate: '2025-07-01' length: 12 type: automatic frequency: monthly pauseCollectionFor: 0 customFields: - name: yourCustomField value: abc123 headers: location: description: URI reference to created resource. schema: *ref_24 examples: *ref_25 '400': description: Validation error content: application/problem+json: schema: type: object properties: *ref_9 required: *ref_10 examples: validationError: summary: Bad Request description: One or more validation errors occurred value: *ref_11 idempotentKeyMissing: summary: Idempotency key missing description: Idempotency key must be supplied value: *ref_26 idempotentKeyInUse: summary: Idempotency key in use description: Idempotency key in use value: *ref_29 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '406': description: Not acceptable content: *ref_19 '409': description: Conflict content: *ref_104 '415': description: Unsupported media type content: *ref_105 '500': description: An error has occured content: *ref_14 get: tags: - Subscriptions summary: List subscriptions description: "Use this method to return a [paginated](https://docs.payroc.com/api/pagination) list of subscriptions. \n\nNote: If you want to view the details of a specific subscription and you have its subscriptionId, use our [Retrieve subscription](https://docs.payroc.com/api/schema/repeat-payments/subscriptions/retrieve) method. \n\nUse query parameters to filter the list of results that we return, for example, to search for subscriptions for a customer, a payment plan, or frequency. \n\nOur gateway returns information about the following for each subscription in the list: \n\n-\tPayment plan the subscription is linked to. \n-\tSecure token that represents cardholder’s payment details. \n-\tCurrent state of the subscription, including its status, next due date, and invoices. \n-\tFees for setup and the cost of the recurring order. \n-\tSubscription length, end date, and frequency. \n\nFor each subscription, we also return the subscriptionId, the paymentPlanId, and the secureTokenId, which you can use to perform follow-actions. \n" operationId: listSubscriptions parameters: - name: processingTerminalId in: path required: true description: Unique identifier that we assigned to the terminal. schema: *ref_96 examples: *ref_97 - name: customerName in: query description: Filter by the customer's name. schema: maxLength: 50 minLength: 1 type: string examples: example: value: Sarah%20Hazel%20Hopper - name: last4 in: query description: Filter by the last four digits of the card or account number. schema: pattern: '[0-9]{4}' type: string examples: example: value: '7062' - name: paymentPlan in: query description: Filter by the name of the payment plan. schema: &ref_395 maxLength: 128 minLength: 1 type: string examples: &ref_396 example: value: Premium%20Club - name: frequency in: query description: Filter by the frequency of subscription payments. schema: &ref_397 type: string enum: - weekly - fortnightly - monthly - quarterly - yearly examples: &ref_398 example: value: monthly - name: status in: query description: Filter by the current status of the subscription. schema: &ref_399 type: string enum: - active - completed - suspended - cancelled examples: &ref_400 example: value: active - name: endDate in: query description: | Format: `YYYY-MM-DD` Filter subscriptions that end on a specific date. schema: &ref_401 type: string format: date examples: &ref_402 example: value: '2025-07-01' - name: nextDueDate in: query description: | Format: `YYYY-MM-DD` Filter subscriptions by the date that the next payment is collected. schema: &ref_403 type: string format: date examples: &ref_404 example: value: '2024-08-01' - name: before in: query description: | Return the previous page of results before the value that you specify. You can’t send the before parameter in the same request as the after parameter. schema: *ref_32 examples: *ref_33 - name: after in: query description: | Return the next page of results after the value that you specify. You can’t send the after parameter in the same request as the before parameter. schema: *ref_34 examples: *ref_35 - name: limit in: query description: Limit the maximum number of results that we return for each page. schema: *ref_36 examples: *ref_37 responses: '200': description: Successful request. Returns a paginated list of subscriptions. content: application/json: schema: required: &ref_644 - count - data - hasMore - limit type: object allOf: &ref_645 - type: object description: Contains the pagination properties that you use to navigate through a list of results. properties: *ref_38 - type: object properties: data: type: array description: Array of subscriptions. items: required: *ref_131 type: object properties: *ref_132 examples: paginatedResults: summary: Paginated Subscription description: Example of Paginated Subscription value: &ref_934 limit: 2 count: 2 hasMore: true data: - subscriptionId: SubRef7654 processingTerminalId: '1234001' paymentPlan: paymentPlanId: PlanRef8765 name: Monthly Premium Club subscription link: rel: self method: GET href: https://api.payroc.com/v1/processing-terminals/1234001/payment-plans/PlanRef8765 secureToken: secureTokenId: MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa customerName: Sarah Hazel Hopper token: '296753123456' status: notValidated link: rel: self method: GET href: https://api.payroc.com/v1/processing-terminals/1234001/secure-tokens/MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa name: Premium Club description: Monthly Premium Club subscription currency: USD setupOrder: orderId: OrderRef6543 amount: 4999 description: Initial setup fee for Premium Club subscription recurringOrder: amount: 4999 currentState: status: active nextDueDate: '2024-08-02' paidInvoices: 1 outstandingInvoices: 11 startDate: '2024-07-02' endDate: '2025-08-01' length: 0 type: automatic frequency: monthly pauseCollectionFor: 0 - subscriptionId: SubRef8543 processingTerminalId: '1234001' paymentPlan: paymentPlanId: PlanRef7654 name: Pie it Forward charitable trust donation link: rel: self method: GET href: https://api.payroc.com/v1/processing-terminals/1234001/payment-plans/PlanRef7654 secureToken: secureTokenId: MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa customerName: Sarah Hazel Hopper token: '296753123456' status: notValidated link: rel: self method: GET href: https://api.payroc.com/v1/processing-terminals/1234001/secure-tokens/MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa name: Pie It Forward description: Pie It Forward charitable trust donation currency: USD setupOrder: orderId: OrderRef7654 amount: 3999 recurringOrder: amount: 3999 currentState: status: active nextDueDate: '2024-04-11' paidInvoices: 1 outstandingInvoices: 11 startDate: '2024-07-02' endDate: '2024-07-02' length: 0 type: automatic frequency: yearly pauseCollectionFor: 0 customFields: - name: yourCustomField value: abc123 links: - rel: next method: get href: https://api.payroc.com/v1/processing-terminals/1234001/subscriptions?limit=2&after=SubRef8543 - rel: previous method: get href: https://api.payroc.com/v1/processing-terminals/1234001/subscriptions?limit=2&before=SubRef7654 noActivity: summary: No records found description: Valid request, but no records match the criteria. value: *ref_55 '400': description: Invalid request content: *ref_15 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '406': description: Not acceptable content: *ref_19 '500': description: An error has occured content: *ref_14 /processing-terminals/{processingTerminalId}/subscriptions/{subscriptionId}: get: tags: - Subscriptions summary: Retrieve subscription description: "Use this method to retrieve information about a subscription. \n\nTo retrieve a subscription, you need its subscriptionId. You sent the subscriptionId in the request of the [Create subscription](https://docs.payroc.com/api/schema/repeat-payments/subscriptions/create) method. \n\n**Note:** If you don't have the subscriptionId, use our [List subscriptions](https://docs.payroc.com/api/schema/repeat-payments/subscriptions/list) method to search for the subscription. \n\nOur gateway returns information about the following for the subscription: \n\n-\tPayment plan the subscription is linked to. \n-\tSecure token that represents cardholder’s payment details. \n-\tCurrent state of the subscription, including its status, next due date, and invoices. \n-\tFees for setup and the cost of the recurring order. \n-\tSubscription length, end date, and frequency. \n\nWe also return the paymentPlanId and the secureTokenId, which you can use to perform follow-on actions. \n" operationId: getSubscription parameters: - name: processingTerminalId in: path required: true description: Unique identifier that we assigned to the terminal. schema: *ref_96 examples: *ref_97 - name: subscriptionId in: path description: Unique identifier that the merchant assigned to the subscription. required: true schema: &ref_135 maxLength: 48 minLength: 1 type: string examples: &ref_136 example: value: SubRef7654 responses: '200': description: Successful request. Returns the requested subscription. content: application/json: schema: required: *ref_131 type: object properties: *ref_132 examples: subscriptionWithSurcharge: summary: Subscription with surcharge description: Subscription with surcharge value: *ref_133 subscriptionWithConvenienceFee: summary: Subscription with convenience fee description: Subscription with convenience fee value: *ref_134 '400': description: Invalid request content: *ref_15 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '404': description: Resource not found content: *ref_18 '406': description: Not acceptable content: *ref_19 '500': description: An error has occured content: *ref_14 patch: tags: - Subscriptions summary: Partially update subscription description: | Use this method to partially update a subscription. Structure your request to follow the [RFC 6902](https://datatracker.ietf.org/doc/html/rfc6902) standard. To update a subscription, you need its subscriptionId, which you sent in the request of the [Create subscription](https://docs.payroc.com/api/schema/repeat-payments/subscriptions/create) method. **Note:** If you don't have the subscriptionId, use our [List subscriptions](https://docs.payroc.com/api/schema/repeat-payments/subscriptions/list) method to search for the payment. You can update all of the properties of the subscription except for the following: **Can't delete** - recurringOrder - description - name **Can't perform any PATCH operation** - currentState - type - frequency - paymentPlan operationId: updateSubscription parameters: - name: Idempotency-Key in: header required: true 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). schema: *ref_22 examples: *ref_23 - name: processingTerminalId in: path required: true description: Unique identifier that we assigned to the terminal. schema: *ref_96 examples: *ref_97 - name: subscriptionId in: path description: Unique identifier that the merchant assigned to the subscription. required: true schema: *ref_135 examples: *ref_136 requestBody: required: true content: application/json: schema: type: array description: A JSON Patch document as defined by RFC 6902. items: *ref_101 example: *ref_102 examples: patchSubscriptionRealistic: summary: Update subscription description: | Make changes to a subscription. Structure your request to follow the [RFC 6902](https://datatracker.ietf.org/doc/html/rfc6902) standard. value: &ref_936 - op: replace path: /setupOrder/amount value: 2999 - op: replace path: /recurringOrder/amount value: 2999 - op: replace path: /frequency value: yearly patchOperations: summary: Example patch operations that apply the RFC 6902 standard description: | Example patch operations that apply the RFC 6902 standard. value: *ref_103 responses: '200': description: Successful request. We have updated the subscription. content: application/json: schema: required: *ref_131 type: object properties: *ref_132 examples: subscriptionWithSurcharge: summary: Subscription with surcharge description: Subscription with surcharge value: *ref_133 subscriptionWithConvenienceFee: summary: Subscription with convenience fee description: Subscription with convenience fee value: *ref_134 '400': description: Validation error content: application/problem+json: schema: type: object properties: *ref_9 required: *ref_10 examples: validationError: summary: Bad Request description: One or more validation errors occurred value: *ref_11 idempotentKeyMissing: summary: Idempotency key missing description: Idempotency key must be supplied value: *ref_26 idempotentKeyInUse: summary: Idempotency key in use description: Idempotency key in use value: *ref_29 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '404': description: Resource not found content: *ref_18 '406': description: Not acceptable content: *ref_19 '409': description: Conflict content: *ref_104 '415': description: Unsupported media type content: *ref_105 '500': description: An error has occured content: *ref_14 /processing-terminals/{processingTerminalId}/subscriptions/{subscriptionId}/deactivate: post: tags: - Subscriptions summary: Deactivate subscription description: | Use this method to deactivate a subscription. To deactivate a subscription, you need its subscriptionId, which you sent in the request of the [Create Subscription](https://docs.payroc.com/api/schema/repeat-payments/subscriptions/create) method. **Note:** If you don't have the subscriptionId, use our [List Subscriptions](https://docs.payroc.com/api/schema/repeat-payments/subscriptions/list) method to search for the subscription. If your request is successful, our gateway stops taking payments from the customer. To reactivate the subscription, use our [Reactivate Subscription](https://docs.payroc.com/api/schema/payments/subscriptions/reactivate) method. operationId: deactivateSubscription parameters: - name: processingTerminalId in: path required: true description: Unique identifier that we assigned to the terminal. schema: *ref_96 examples: *ref_97 - name: subscriptionId in: path description: Unique identifier that the merchant assigned to the subscription. required: true schema: *ref_135 examples: *ref_136 responses: '200': description: Successful request. We deactivated the subscription. content: application/problem+json: schema: required: *ref_131 type: object properties: *ref_132 examples: deactivateSubscription: summary: Deactivate subscription description: Deactivate a subscription value: &ref_937 subscriptionId: SubRef7654 processingTerminalId: '1234001' paymentPlan: paymentPlanId: PlanRef8765 name: Monthly Premium Club subscription link: rel: self method: GET href: https://api.payroc.com/v1/processing-terminals/1234001/payment-plans/PlanRef8765 secureToken: secureTokenId: MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa customerName: Sarah Hazel Hopper token: '296753123456' status: notValidated link: rel: self method: GET href: https://api.payroc.com/v1/processing-terminals/1234001/secure-tokens/MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa name: Premium Club description: Monthly Premium Club subscription currency: USD setupOrder: orderId: OrderRef6543 amount: 4999 description: Initial setup fee for Premium Club subscription breakdown: subtotal: 4347 taxes: - name: Sales Tax rate: 5 surcharge: amount: 217 percentage: 5 recurringOrder: amount: 4999 description: Monthly Premium Club subscription breakdown: subtotal: 4347 taxes: - name: Sales Tax rate: 5 surcharge: amount: 217 percentage: 5 currentState: status: cancelled nextDueDate: '2024-08-02' paidInvoices: 0 outstandingInvoices: 3 startDate: '2024-07-02' endDate: '2025-07-01' length: 12 type: automatic frequency: monthly pauseCollectionFor: 0 customFields: - name: yourCustomField value: abc123 '400': description: Invalid request content: *ref_15 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '404': description: Resource not found content: *ref_18 '406': description: Not acceptable content: *ref_19 '409': description: Conflict content: *ref_104 '415': description: Unsupported media type content: *ref_105 '500': description: An error has occured content: *ref_14 /processing-terminals/{processingTerminalId}/subscriptions/{subscriptionId}/reactivate: post: tags: - Subscriptions summary: Re-activate subscription description: | Use this method to reactivate a subscription. To reactivate a subscription, you need its subscriptionId, which you sent in the request of the [Create Subscription](https://docs.payroc.com/api/schema/repeat-payments/subscriptions/create) method. **Note:** If you don't have the subscriptionId, use our [List Subscriptions](https://docs.payroc.com/api/schema/repeat-payments/subscriptions/list) method to search for the subscription. If your request is successful, our gateway restarts taking payments from the customer. To deactivate the subscription, use our [Deactivate Subscription](https://docs.payroc.com/api/schema/repeat-payments/subscriptions/deactivate) method. operationId: reactivateSubscription parameters: - name: processingTerminalId in: path required: true description: Unique identifier that we assigned to the terminal. schema: *ref_96 examples: *ref_97 - name: subscriptionId in: path description: Unique identifier that the merchant assigned to the subscription. required: true schema: *ref_135 examples: *ref_136 responses: '200': description: Successful request. We re-activated the subscription. content: application/json: schema: required: *ref_131 type: object properties: *ref_132 examples: subscriptionWithSurcharge: summary: Subscription with surcharge description: Subscription with surcharge value: *ref_133 subscriptionWithConvenienceFee: summary: Subscription with convenience fee description: Subscription with convenience fee value: *ref_134 '400': description: Invalid request content: *ref_15 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '404': description: Resource not found content: *ref_18 '406': description: Not acceptable content: *ref_19 '409': description: Conflict content: *ref_104 '415': description: Unsupported media type content: *ref_105 '500': description: An error has occured content: *ref_14 /processing-terminals/{processingTerminalId}/subscriptions/{subscriptionId}/pay: post: tags: - Subscriptions summary: Pay manual subscription description: | Use this method to manually collect a payment linked to a subscription. You can manually collect a payment only if the merchant chose not to let our gateway automatically collect each payment. To manually collect a payment, you need the subscriptionId of the subscription that's linked to the payment. You sent the subscriptionId in the request of the [Create Subscription](https://docs.payroc.com/api/schema/repeat-payments/subscriptions/create) method. **Note:** If you don't have the subscriptionId, use our [List Subscriptions](https://docs.payroc.com/api/schema/repeat-payments/subscriptions/list) method to search for the subscription. The request includes an order object that contains information about the amount that you want to collect. In the response, our gateway returns information about the payment and a paymentId. You can use the paymentId in follow-on actions with the [Payments](https://docs.payroc.com/api/schema/card-payments/payments) endpoints or [Bank Transfer Payments](https://docs.payroc.com/api/schema/bank-transfer-payments/payments) endpoints. operationId: paySubscription parameters: - name: Idempotency-Key in: header required: true 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). schema: *ref_22 examples: *ref_23 - name: processingTerminalId in: path required: true description: Unique identifier that we assigned to the terminal. schema: *ref_96 examples: *ref_97 - name: subscriptionId in: path description: Unique identifier that the merchant assigned to the subscription. required: true schema: *ref_135 examples: *ref_136 requestBody: content: application/json: schema: required: &ref_650 - order properties: &ref_651 operator: maxLength: 50 minLength: 0 type: string description: Operator who initiated the request. order: description: Object that contains information about the payment. type: object allOf: *ref_137 customFields: type: array description: | Array of customField objects. items: required: *ref_129 type: object properties: *ref_130 examples: subscriptionPaymentRequest: summary: Subscription manual payment description: Subscription manual payment value: &ref_938 operator: Jane order: amount: 4999 description: Monthly Premium Club subscription orderId: OrderRef6543 required: true responses: '201': description: Successful request. We have processed the payment for the subscription. content: application/json: schema: required: &ref_652 - subscriptionId - processingTerminalId - payment - secureToken - currentState type: object properties: &ref_653 subscriptionId: type: string description: Unique identifier that the merchant assigned to the subscription. example: SubRef7654 processingTerminalId: type: string description: Unique identifier of the terminal that the subscription is linked to. example: '1234001' payment: required: &ref_233 - amount - currency - dateTime - paymentId - status - responseCode - responseMessage type: object description: Object that contains information about a payment. properties: &ref_234 paymentId: maxLength: 10 minLength: 10 type: string description: Unique identifier of the payment. example: M2MJOG6O2Y dateTime: type: string format: date-time description: Date and time that the payment was processed. example: '2024-07-02T15:30:00Z' currency: type: string description: Currency of the transaction. The value for the currency follows the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard. enum: *ref_83 amount: type: integer format: int64 description: Amount of the payment. This value is in the currency’s lowest denomination, for example, cents. example: 4999 status: type: string description: Current status of the payment. enum: - ready - pending - declined - complete - referral - pickup - reversal - returned - admin - expired - accepted example: complete responseCode: type: string 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. enum: - A - D - E - P - R - C example: A responseMessage: maxLength: 48 minLength: 1 type: string description: Response description from the processor. example: Transaction approved link: type: object readOnly: true description: Object that contains HATEOAS links for the resource. properties: *ref_4 required: *ref_5 example: *ref_6 secureToken: required: *ref_138 type: object description: Object that contains information about the secure token. properties: *ref_139 currentState: required: *ref_140 type: object description: A snapshot of the subscription's current state. properties: *ref_141 customFields: type: array description: | Array of customField objects. items: required: *ref_129 type: object properties: *ref_130 examples: subscriptionPaymentResponse: summary: Subscription manual payment description: Subscription manual payment value: &ref_939 subscriptionId: SubRef7654 processingTerminalId: '1234001' payment: paymentId: M2MJOG6O2Y dateTime: '2024-07-02T15:30:00Z' amount: 4999 currency: USD status: ready responseCode: A responseMessage: Transaction approved link: rel: self method: GET href: https://api.payroc.com/v1/bank-transfer-payments/M2MJOG6O2Y secureToken: secureTokenId: MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa customerName: Sarah Hazel Hopper token: '296753123456' status: notValidated link: rel: self method: GET href: https://api.payroc.com/v1/processing-terminals/1234001/secure-tokens/MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa currentState: status: active nextDueDate: '2024-08-02' paidInvoices: 1 outstandingInvoices: 2 customFields: - name: yourCustomField value: abc123 headers: location: description: URI reference to created resource. schema: *ref_24 examples: *ref_25 '400': description: Validation error content: application/problem+json: schema: type: object properties: *ref_9 required: *ref_10 examples: validationError: summary: Bad Request description: One or more validation errors occurred value: *ref_11 idempotentKeyMissing: summary: Idempotency key missing description: Idempotency key must be supplied value: *ref_26 idempotentKeyInUse: summary: Idempotency key in use description: Idempotency key in use value: *ref_29 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '404': description: Resource not found content: *ref_18 '406': description: Not acceptable content: *ref_19 '409': description: Conflict content: *ref_104 '415': description: Unsupported media type content: *ref_105 '500': description: An error has occured content: *ref_14 /processing-terminals/{processingTerminalId}/secure-tokens: post: tags: - Secure tokens summary: Create secure token description: | Use this method to create a secure token that represents a customer's payment details. When you create a secure token, you need to generate and provide a secureTokenId that you use to run follow-on actions: - [Retrieve Secure Token](https://docs.payroc.com/api/schema/tokenization/secure-tokens/retrieve) – View the details of the secure token. - [Delete Secure Token](https://docs.payroc.com/api/schema/tokenization/secure-tokens/delete) – Delete the secure token. - [Update Secure Token](https://docs.payroc.com/api/schema/tokenization/secure-tokens/partially-update) – Update the details of the secure token. - [Update Account Details](https://docs.payroc.com/api/schema/tokenization/secure-tokens/update-account) – Update the secure token with the details from a single-use token. **Note:** If you don't generate a secureTokenId to identify the token, our gateway generates a unique identifier and returns it in the response. If the request is successful, our gateway returns a token that the merchant can use in transactions instead of the customer's sensitive payment details, for example, when they [run a sale](https://docs.payroc.com/api/schema/card-payments/payments/create). operationId: createSecureToken parameters: - name: Idempotency-Key in: header required: true 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). schema: *ref_22 examples: *ref_23 - name: processingTerminalId in: path required: true description: Unique identifier that we assigned to the terminal. schema: *ref_96 examples: *ref_97 requestBody: content: application/json: schema: required: &ref_683 - source type: object properties: &ref_684 secureTokenId: maxLength: 200 minLength: 1 type: string description: | Unique identifier that the merchant created for the secure token that represents the customer's payment details. If the merchant doesn't create a secureTokenId, the gateway generates one and returns it in the response. example: MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa operator: maxLength: 50 minLength: 1 type: string description: Operator who saved the customer's payment details. example: Jane mitAgreement: type: string description: | Indicates how the merchant can use the customer's card details, as agreed by the customer: - `unscheduled` - Transactions for a fixed or variable amount that are run at a certain pre-defined event. - `recurring` - Transactions for a fixed amount that are run 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 are run at regular intervals, for example, monthly. Installment transactions have a fixed duration. enum: - unscheduled - recurring - installment example: recurring customer: type: object description: Object that contains the customer's contact details and address information. properties: &ref_176 firstName: type: string description: Customer's first name. maxLength: 60 minLength: 0 example: Sarah lastName: type: string description: Customer's last name. maxLength: 60 minLength: 0 example: Hopper dateOfBirth: type: string format: date description: Customer's date of birth. The format for this value is **YYYY-MM-DD**. example: '1990-07-15' referenceNumber: type: string description: | Identifier of the transaction, also known as a customer code. For requests, you must send a value for **referenceNumber** if the customer provides one. maxLength: 48 minLength: 0 example: CustomerCode234567 billingAddress: description: Object that contains information about the address that the card is registered to. required: *ref_0 type: object title: address properties: *ref_1 shippingAddress: description: Object that contains information about the customer and their shipping address. type: object properties: &ref_213 recipientName: maxLength: 50 minLength: 0 type: string description: Recipient's name. example: Sarah Hopper address: required: *ref_0 type: object title: address description: Object that contains information about the address. properties: *ref_1 contactMethods: type: array uniqueItems: true 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" items: discriminator: *ref_2 oneOf: *ref_3 notificationLanguage: type: string format: iso-639-1 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. enum: - en - fr maxLength: 2 minLength: 2 example: en ipAddress: required: &ref_177 - type - value type: object writeOnly: true description: Object that contains the IP address of the device that sent the request. properties: &ref_178 type: type: string description: Internet protocol version of the IP address. enum: - ipv4 - ipv6 value: type: string description: IP address of the device. source: description: "Polymorphic object that contains the payment method to tokenize. \n\nThe value of the type parameter determines which variant you should use: \n-\t`ach` - Automated Clearing House (ACH) details\n-\t`pad` - Pre-authorized debit (PAD) details\n-\t`card` - Payment card details\n-\t`singleUseToken` - Single-use token details\n" type: object discriminator: propertyName: type mapping: ach: '#/components/schemas/achPayload' pad: '#/components/schemas/padPayload' card: '#/components/schemas/cardPayload' singleUseToken: '#/components/schemas/singleUseTokenPayload' oneOf: - required: &ref_163 - type - accountNumber - nameOnAccount - routingNumber type: object writeOnly: true title: ach description: Object that contains information about the payment details for the customer’s automated clearing house (ACH) transactions. properties: &ref_164 type: type: string description: | Indicates the type of bank account details the customer is using: - **ACH** - Customer's bank account is in the United States. - **PAD** - Customer's bank account is in Canada. enum: - ach example: ach accountType: type: string description: | Indicates the customer’s account type. **Note:** For bank account details, send a value for accountType. enum: - checking - savings example: checking secCode: type: string description: | Indicates how the customer authorized the ACH transaction. Send one of the following values: - `web` – Online transaction. - `tel` – Telephone transaction. - `ccd` – Corporate credit card or debit card transaction. - `ppd` – Pre-arranged transaction. enum: - web - tel - ccd - ppd example: web nameOnAccount: maxLength: 50 minLength: 1 type: string description: Customer's name. example: Shara Hazel Hopper accountNumber: maxLength: 17 minLength: 4 pattern: ^[0-9]*$ type: string description: | Customer’s bank account number. **Note:** In responses, our gateway shows only the last four digits of the account number, for example, `*****5929`. example: '1234567890' routingNumber: maxLength: 9 minLength: 9 pattern: ^[0-9]*$ type: string description: Nine-digit number that identifies the customer's bank. example: '123456789' - required: &ref_165 - type - nameOnAccount - accountNumber - transitNumber - institutionNumber type: object writeOnly: true title: pad description: Object that contains information about the payment details for the customer’s preauthorized electronic debit (PAD) transactions. properties: &ref_166 type: type: string description: | Indicates the type of bank account details the customer is using: - **ACH** - Customer's bank account is in the United States. - **PAD** - Customer's bank account is in Canada. enum: - pad example: pad accountType: type: string description: | Indicates the customer’s account type. **Note:** For bank account details, send a value for accountType. enum: - checking - savings example: checking nameOnAccount: maxLength: 29 minLength: 1 type: string description: Customer's name. example: Sarah Hazel Hopper accountNumber: maxLength: 12 minLength: 7 pattern: ^[0-9]*$ type: string description: | Customer's account number. **Note:** In responses, our gateway shows only the last four digits of the account number, for example, `*****5929`. example: '1234567890' transitNumber: maxLength: 5 minLength: 5 pattern: ^[0-9]*$ type: string description: Five-digit number that identifies the customer's bank branch. example: '76543' institutionNumber: maxLength: 3 minLength: 3 pattern: ^[0-9]*$ type: string description: Three-digit number that identifies the customer's bank. example: '543' - required: &ref_167 - type - cardDetails type: object writeOnly: true title: card description: Object that contains information about the customer’s payment card. properties: &ref_168 type: type: string description: Method that the terminal used to take the payment. enum: - card example: card accountType: type: string description: | Indicates the customer’s account type. **Note:** Send a value for accountType only for bank account details. enum: - checking - savings example: checking cardDetails: type: object description: | Polymorphic object that contains payment card information. The value of the entryMethod parameter determines which variant you should use: - `raw` - Unencrypted payment data directly from the device. - `icc` - Payment data that the device captured from the chip. - `keyed` - Payment data that the merchant entered manually. - `swiped` - Payment data that the device captured from the magnetic strip. discriminator: propertyName: entryMethod mapping: raw: '#/components/schemas/rawCardDetails' icc: '#/components/schemas/iccCardDetails' keyed: '#/components/schemas/keyedCardDetails' swiped: '#/components/schemas/swipedCardDetails' oneOf: - required: &ref_661 - entryMethod - device - rawData type: object title: raw description: Object that contains information about the unencrypted card details. properties: &ref_662 entryMethod: type: string description: Method that the terminal used to capture the card details. enum: - raw example: raw downgradeTo: type: string description: | If an offline transaction is not approved using the initial entry method, reprocess the transaction using a downgraded entry method. For example, an Integrated Circuit Card (ICC) transaction can be downgraded to a swiped transaction or to a keyed transaction. enum: - keyed - swiped example: swiped device: required: &ref_142 - model - serialNumber type: object description: Object that contains information about the physical device the merchant used to capture the customer’s card details. properties: &ref_143 model: type: string description: Model of the device that the merchant used to process the transaction. enum: - bbposChp - bbposChp2x - bbposChp3x - bbposRambler - bbposWp - bbposWp2 - bbposWp3 - genericCtlsMsr - genericMsr - idtechAugusta - idtechMinismart - idtechSredkey - idtechVp3300 - idtechVp5300 - idtechVp6300 - idtechVp6800 - ingenicoAxiumDx4000 - ingenicoAxiumDx8000 - ingenicoAxiumEx8000 - ingenicoIct220 - ingenicoIpp320 - ingenicoIpp350 - ingenicoIuc285 - ingenicoL3000 - ingenicoL7000 - ingenicoS2000 - ingenicoS3000 - ingenicoS4000 - ingenicoS5000 - ingenicoS7000 - paxA80 - paxA920 - paxA920Pro - paxE500 - paxE700 - paxE800 - paxIm30 - uic680 - uicBezel8 example: paxA920 category: type: string description: Indicates if the device is attended or unattended. enum: - attended - unattended default: attended example: attended serialNumber: maxLength: 64 minLength: 1 type: string description: Serial number of the physical device. example: '1850010868' firmwareVersion: type: string description: Firmware version of the physical device. example: v1.2.3 config: required: &ref_659 - quickChip type: object description: Object that contains information about the configuration of the POS terminal. properties: &ref_660 quickChip: type: boolean default: false description: Indicates if Quick Chip mode is active on a merchant’s POS terminal. example: false rawData: maxLength: 2147483647 minLength: 1 type: string format: hexadecimal description: Unencrypted data from the POS terminal. example: A1B2C3D4E5F67890ABCD1234567890ABCDEF1234567890ABCDEF1234567890ABCDEF cardholderSignature: type: string description: Cardholder's signature. For more information about how to format the signature, go to [How to send a signature to our gateway](https://docs.payroc.com/knowledge/basic-concepts/signature-capture). example: a1b1c012345678a000b000c0012345d0e0f010g10061a031i001j071k0a1b0c1d0e1234567890120f1g0h1i0j1k0a1b0123451c012d0e1f0g1h0i1j123k1a1b1c1d1e1f1g123h1i1j1k1a1b1c1d1e1f1g123h123i1j123k12340a120a12345b012c0123012d0d1e0f1g0h1i123j123k10000 - required: &ref_665 - entryMethod - device - iccData type: object title: icc description: Object that contains information about the Integrated Circuit Card (ICC). properties: &ref_666 entryMethod: type: string description: Method that the terminal used to capture the card details. enum: - icc example: icc downgradeTo: type: string description: | If an offline transaction is not approved using the initial entry method, reprocess the transaction using a downgraded entry method. For example, an Integrated Circuit Card (ICC) transaction can be downgraded to a swiped transaction or a keyed transaction. enum: - keyed - swiped example: swiped device: required: &ref_144 - model - dataKsn - serialNumber type: object description: Object that contains information about the encryption details of the POS terminal. allOf: &ref_145 - required: *ref_142 type: object description: Object that contains information about the physical device the merchant used to capture the customer’s card details. properties: *ref_143 - type: object properties: dataKsn: maxLength: 20 minLength: 20 type: string format: hexadecimal description: Key serial number. example: A1B2C3D4E5F67890ABCD iccData: type: string format: hexadecimal description: Cardholder data from the ICC. The data consists of EMV tags in Tag-Length-Value (TLV) format. example: 5A08476173921001010F firstDigitOfPan: maxLength: 1 minLength: 1 type: string description: First digit of the card number. example: '4' cardholderSignature: type: string description: Cardholder's signature. For more information about how to format the signature, go to [How to send a signature to our gateway](https://docs.payroc.com/knowledge/basic-concepts/signature-capture). example: 012345678a000b000c0012345d0e0f010g10061a031i001j071k0a1b0c1d0e1234567890120f1g0h1i0j1k0a1b0123451c012d0e1f0g1h0i1j123k1a1b1c1d1e1f1g123h1i1j1k1a1b1c1d1e1f1g123h123i1j123k12340a120a12345b012c0123012d0d1e0f1g0h1i123j123k1a1b1c0000 ebtDetails: type: object required: &ref_146 - benefitCategory description: Object that contains information about the Electronic Benefit Transfer (EBT) transaction. allOf: &ref_147 - type: object required: &ref_221 - benefitCategory description: Object that contains information about the Electronic Benefit Transfer (EBT) transaction. properties: &ref_222 benefitCategory: type: string description: | Indicates if the balance relates to an EBT Cash account or an EBT SNAP account. - `cash` – EBT Cash - `foodStamp` – EBT SNAP enum: - cash - foodStamp example: cash withdrawal: type: boolean description: | Indicates whether the customer wants to withdraw cash. **Note:** Cash withdrawals are available only from EBT Cash accounts. example: false - type: object properties: voucher: required: &ref_663 - approvalCode - serialNumber type: object description: | Object that contains information about the EBT voucher. **Note:** Vouchers are available only for EBT SNAP payments. properties: &ref_664 approvalCode: maxLength: 6 minLength: 6 type: string description: Authorization code that the processor issued for the transaction. example: '123456' serialNumber: maxLength: 15 minLength: 7 type: string description: Serial number of the voucher. example: SN123456789 - required: &ref_673 - entryMethod - keyedData type: object title: keyed description: Object that contains information about the keyed card details. properties: &ref_674 entryMethod: type: string description: Method that the terminal used to capture the card details. enum: - keyed example: keyed keyedData: type: object description: "Polymorphic object that contains payment card details that the merchant manually entered into the device. \n\nThe value of the dataFormat parameter determines which variant you should use: \n-\t`fullyEncrypted` - Some payment card details are encrypted.\n-\t`partiallyEncrypted` - Payment card details are in plain text.\n-\t`plainText` - All payment card details are encrypted.\n" discriminator: propertyName: dataFormat mapping: fullyEncrypted: '#/components/schemas/fullyEncryptedKeyedDataFormat' partiallyEncrypted: '#/components/schemas/partiallyEncryptedKeyedDataFormat' plainText: '#/components/schemas/plainTextKeyedDataFormat' oneOf: - required: &ref_667 - dataFormat - device - encryptedData type: object title: fullyEncrypted description: Object that contains information about the encrypted card data for keyed transactions. properties: &ref_668 dataFormat: type: string description: "Indicates the data format of the customer’s card data.\n-\t`plainText` – Data is not truncated and shows the raw data.\n-\t`fullyEncrypted` – Data is truncated to show only the first digit of the customer’s account number.\n-\t`partiallyEncrypted` – Data is truncated to show only the first six digits and the last four digits of the customer’s card number.\n" enum: - fullyEncrypted example: fullyEncrypted device: required: *ref_144 type: object description: Object that contains information about the encryption details of the POS terminal. allOf: *ref_145 encryptedData: maxLength: 2147483647 minLength: 1 type: string description: Encrypted card data. format: hexadecimal example: A1B2C3D4E5F67890ABCD1234567890ABCDEF1234567890ABCDEF1234567890ABCDEF firstDigitOfPan: maxLength: 1 minLength: 1 type: string description: First digit of the customer’s card number. example: '4' - required: &ref_669 - dataFormat - device - encryptedPan - expiryDate - maskedPan type: object title: partiallyEncrypted description: Object that contains information about the partially-encrypted card data for keyed transactions. properties: &ref_670 dataFormat: type: string description: "Indicates the data format of the customer’s card data.\n-\t`plainText` – Data is not truncated and shows the raw data.\n-\t`fullyEncrypted` – Data is truncated to show only the first digit of the customer’s account number.\n-\t`partiallyEncrypted` – Data is truncated to show only the first six digits and the last four digits of the customer’s card number.\n" enum: - partiallyEncrypted example: partiallyEncrypted device: required: *ref_144 type: object description: Object that contains information about the encryption details of the POS terminal. allOf: *ref_145 encryptedPan: maxLength: 2147483647 minLength: 1 type: string format: hexadecimal description: Encrypted card number. example: A1B2C3D4E5F67890ABCD1234567890ABCDEF1234567890ABCDEF1234567890ABCDEF maskedPan: maxLength: 19 minLength: 12 type: string description: | Masked card number. The gateway shows only the first six digits and the last four digits of the account number. For example, `453985******7062`. example: 453985******7062 expiryDate: pattern: '[0-9]{4}' type: string description: Expiry date of the customer’s card. example: '1230' cvv: pattern: '[0-9]{3,4}' type: string description: Security code of the customer’s card. example: '234' cvvEncrypted: type: string format: hexadecimal description: Encrypted security code data. issueNumber: pattern: '[0-9]{1,2}' type: string description: Issue number of the customer’s card. example: '78' - required: &ref_671 - dataFormat - cardNumber type: object title: plainText description: Object that contains information about the plain-text card data for keyed transactions. properties: &ref_672 dataFormat: type: string description: "Indicates the data format of the customer’s card data.\n-\t`plainText` – Data is not truncated and shows the raw data.\n-\t`fullyEncrypted` – Data is truncated to show only the first digit of the customer’s account number.\n-\t`partiallyEncrypted` – Data is truncated to show only the first six digits and the last four digits of the customer’s card number.\n" enum: - plainText example: plainText device: required: *ref_142 type: object description: Object that contains information about the physical device the merchant used to capture the customer’s card details. properties: *ref_143 cardNumber: maxLength: 19 minLength: 12 type: string description: Customer’s card number. example: '4539858876047062' expiryDate: pattern: '[0-9]{4}' type: string description: | Expiry date of the customer’s card. **Note:** We require you to send an expiry date for most BIN lookups and electronic voucher transactions. example: '1230' cvv: pattern: '[0-9]{3,4}' type: string description: Security code of the customer’s card. example: '234' issueNumber: pattern: '[0-9]{1,2}' type: string description: Issue number of the customer’s card. example: '78' cardholderName: maxLength: 50 minLength: 1 type: string description: Cardholder’s name. example: Sarah Hazel Hopper cardholderSignature: type: string description: Cardholder's signature. For more information about how to format the signature, go to [How to send a signature to our gateway](https://docs.payroc.com/knowledge/basic-concepts/signature-capture). example: a1b1c012345678a000b000c0012345d0e0f010g10061a031i001j071k0a1b0c1d0e1234567890120f1g0h1i0j1k0a1b0123451c012d0e1f0g1h0i1j123k1a1b1c1d1e1f1g123h1i1j1k1a1b1c1d1e1f1g123h123i1j123k12340a120a12345b012c0123012d0d1e0f1g0h1i123j123k10000 pinDetails: type: object description: Polymorphic object that contains information about the customer's PIN. discriminator: propertyName: dataFormat mapping: dukpt: '#/components/schemas/dukptPinDetails' oneOf: - required: &ref_148 - dataFormat - pin - pinKsn type: object title: dukpt description: Object that contains information about encrypted PIN details. properties: &ref_149 dataFormat: type: string description: Indicates the format of the PIN data. enum: - dukpt example: dukpt pin: maxLength: 2147483647 minLength: 1 type: string description: | Encrypted PIN. **Note:** PIN is encrypted using the DUKPT scheme. format: hexadecimal example: A1B2C3D4E5F67890ABCD1234567890ABCDEF pinKsn: maxLength: 20 minLength: 20 type: string description: Key serial number. format: hexadecimal example: 1234567890ABCDEF1234 ebtDetails: type: object required: *ref_146 description: Object that contains information about the Electronic Benefit Transfer (EBT) transaction. allOf: *ref_147 - required: &ref_679 - entryMethod - swipedData type: object title: swiped description: Object that contains information about the customer’s card details for swiped transactions. properties: &ref_680 entryMethod: type: string description: Method that the terminal used to capture the card details. enum: - swiped example: swiped downgradeTo: type: string description: | If an offline transaction is not approved using the initial entry method, reprocess the transaction using a downgraded entry method. For example, a swiped transaction can be downgraded to a keyed transaction. enum: - keyed - swiped example: swiped swipedData: type: object description: "Polymorphic object that contains payment card details that a device captured from the magnetic strip. \n\nThe value of the dataFormat parameter determines which variant you should use: \n-\t`encrypted` - Payment card details are encrypted.\n-\t`plainText` - Payment card details are in plain text.\n" discriminator: propertyName: dataFormat mapping: encrypted: '#/components/schemas/encryptedSwipedDataFormat' plainText: '#/components/schemas/plainTextSwipedDataFormat' oneOf: - required: &ref_675 - dataFormat - device - encryptedData type: object title: encrypted description: Object that contains information about the encrypted swiped card data. properties: &ref_676 dataFormat: type: string description: Format of the card data. enum: - encrypted example: encrypted device: required: *ref_144 type: object description: Object that contains information about the encryption details of the POS terminal. allOf: *ref_145 encryptedData: maxLength: 2147483647 minLength: 1 type: string format: hexadecimal description: Encrypted data received from the magnetic stripe reader. example: A1B2C3D4E5F67890ABCD1234567890ABCDEF1234567890ABCDEF1234567890ABCDEF firstDigitOfPan: maxLength: 1 minLength: 1 type: string description: First digit of the of the card number. example: '4' fallback: type: boolean description: Indicates that this is a fallback transaction. For example, if there was a technical issue with the chip on the customer's card and the merchant then swiped the card. example: true fallbackReason: type: string description: Reason for the fallback. enum: - technical - repeatFallback - emptyCandidateList example: technical - required: &ref_677 - dataFormat - device - trackData type: object title: plainText description: Object that contains information about plain-text swiped card data. properties: &ref_678 dataFormat: type: string description: | Indicates the method the customer’s card data is encrypted. Send swiped card data in encrypted format or `plainText` format. enum: - plainText example: plainText device: required: *ref_142 type: object description: Object that contains information about the physical device the merchant used to capture the customer’s card details. properties: *ref_143 trackData: maxLength: 256 minLength: 16 type: string description: Customer’s card data from the swiped transaction. example: '1234567890123456789012345678901234567890' fallback: type: boolean description: Indicates that this is a fallback transaction. For example, if there was a technical issue with the chip on the customer's card and the merchant then swiped the card. example: true fallbackReason: type: string description: Reason for the fallback. enum: - technical - repeatFallback - emptyCandidateList example: technical cardholderName: maxLength: 50 minLength: 0 type: string description: Cardholder’s name. example: Sarah Hazel Hopper cardholderSignature: type: string description: Cardholder's signature. For more information about how to format the signature, go to [How to send a signature to our gateway](https://docs.payroc.com/knowledge/basic-concepts/signature-capture). example: a1b1c012345678a000b000c0012345d0e0f010g10061a031i001j071k0a1b0c1d0e1234567890120f1g0h1i0j1k0a1b0123451c012d0e1f0g1h0i1j123k1a1b1c1d1e1f1g123h1i1j1k1a1b1c1d1e1f1g123h123i1j123k12340a120a12345b012c0123012d0d1e0f1g0h1i123j123k10000 pinDetails: type: object description: Polymorphic object that contains information about the customer's PIN. discriminator: propertyName: dataFormat mapping: dukpt: '#/components/schemas/dukptPinDetails' oneOf: - required: *ref_148 type: object title: dukpt description: Object that contains information about encrypted PIN details. properties: *ref_149 ebtDetails: type: object required: *ref_146 description: Object that contains information about the Electronic Benefit Transfer (EBT) transaction. allOf: *ref_147 - required: &ref_181 - type - token type: object writeOnly: true title: singleUseToken description: Object that contains information about the single-use token, which represents the customer’s payment details. properties: &ref_182 type: type: string description: Method that the terminal used to take the payment. enum: - singleUseToken example: singleUseToken accountType: type: string description: | Indicates the customer’s account type. **Note:** Send a value for accountType only if the single-use token represents bank account details. enum: - checking - savings example: checking token: maxLength: 128 minLength: 128 type: string description: Unique token that the gateway assigned to the payment details. example: abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890 pinDetails: type: object description: | Polymorphic object that contains information about a customer's PIN. The value of the dataFormat parameter determines which variant you should use: - `dukpt` - PIN information is encrypted. - `raw` - PIN information is unencrypted. discriminator: propertyName: dataFormat mapping: dukpt: '#/components/schemas/dukptPinDetails' raw: '#/components/schemas/rawPinDetails' oneOf: - required: *ref_148 type: object title: dukpt description: Object that contains information about encrypted PIN details. properties: *ref_149 - required: &ref_681 - dataFormat - pin type: object title: raw description: Object that contains information about the unencrypted PIN details. properties: &ref_682 dataFormat: type: string description: Indicates the format of the PIN data. enum: - raw example: raw pin: maxLength: 2147483647 minLength: 1 type: string description: Customer’s unencrypted PIN. example: '4422' ebtDetails: type: object required: *ref_146 description: Object that contains information about the Electronic Benefit Transfer (EBT) transaction. allOf: *ref_147 secCode: type: string description: | Indicates how the customer authorized the ACH transaction. Send one of the following values: - `web` – Online transaction. - `tel` – Telephone transaction. - `ccd` – Corporate credit card or debit card transaction. - `ppd` – Pre-arranged transaction. enum: - web - tel - ccd - ppd example: web threeDSecure: type: object description: "Polymorphic object that contains authentication information from 3-D Secure. \n\nThe value of the type parameter determines which variant you should use: \n-\t`gatewayThreeDSecure` - Use our gateway to run a 3-D Secure check.\n-\t`thirdPartyThreeDSecure` - Use a third party to run a 3-D Secure check.\n" discriminator: propertyName: type mapping: gatewayThreeDSecure: '#/components/schemas/gatewayThreeDSecure' thirdPartyThreeDSecure: '#/components/schemas/thirdPartyThreeDSecure' oneOf: - required: &ref_183 - serviceProvider - mpiReference type: object title: gateway description: Object that contains the 3-D Secure information from our gateway. properties: &ref_184 serviceProvider: type: string description: Provider of your 3-D Secure protocol. enum: - gateway example: gateway mpiReference: maxLength: 20 minLength: 20 type: string description: Reference that our gateway assigned to the 3-D Secure authentication response. example: MPI45678901234567890 - required: &ref_185 - eci - serviceProvider type: object title: thirdParty description: Object that contains the 3-D Secure information from a third party. properties: &ref_186 serviceProvider: type: string description: Provider of your 3-D Secure protocol. enum: - thirdParty example: thirdParty eci: type: string description: E-commerce indicator (ECI) result of a the 3-D Secure check. enum: - fullyAuthenticated - attemptedAuthentication example: fullyAuthenticated xid: maxLength: 50 minLength: 0 type: string description: Unique transaction identifier that the merchant assigned to the transaction and sent in the authentication request. example: VGhpcyBpcyBhbiBleGFtcGxlIFhJRA== cavv: maxLength: 50 minLength: 0 type: string description: Cardholder Authentication Verification Value (CAVV) that the card issuer provided to prove that they authorized the online payment. example: QWxhZGRpbjpvcGVuIHNlc2FtZQ== dsTransactionId: maxLength: 36 minLength: 0 type: string description: Directory Server Transaction ID that the processor assigned to the request. example: 123e4567-e89b-12d3-a456-426614174000 customFields: type: array description: | Array of customField objects. items: required: *ref_129 type: object properties: *ref_130 examples: createSecureToken: summary: Secure Token description: Secure Token value: &ref_941 operator: Jane mitAgreement: unscheduled customer: firstName: Sarah lastName: Hopper dateOfBirth: '1990-07-15' referenceNumber: Customer-12 billingAddress: address1: 1 Example Ave. address2: Example Address Line 2 address3: Example Address Line 3 city: Chicago state: Illinois country: US postalCode: '60056' shippingAddress: recipientName: Sarah Hopper address: address1: 1 Example Ave. address2: Example Address Line 2 address3: Example Address Line 3 city: Chicago state: Illinois country: US postalCode: '60056' contactMethods: - type: email value: sarah.hopper@example.com notificationLanguage: en ipAddress: type: ipv4 value: 104.18.24.203 source: type: card cardDetails: entryMethod: keyed cardholderName: Sarah Hazel Hopper keyedData: dataFormat: plainText cardNumber: '4539858876047062' expiryDate: '1230' cvv: '234' customFields: - name: yourCustomField value: abc123 required: true responses: '201': description: Successful request. We created a secure token that represents your customer's payment details. content: application/json: schema: required: &ref_151 - processingTerminalId - secureTokenId - source - status - token type: object description: Object that contains information about the secure token. properties: &ref_152 secureTokenId: maxLength: 200 minLength: 0 type: string description: Unique identifier that the merchant created for the secure token that represents the customer's payment details. example: MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa processingTerminalId: maxLength: 50 minLength: 4 type: string description: Unique identifier that we assigned to the terminal. example: '1234001' mitAgreement: type: string description: | Indicates how the merchant can use the customer's card details, as agreed by the customer: - `unscheduled` - Transactions for a fixed or variable amount that are run at a certain pre-defined event. - `recurring` - Transactions for a fixed amount that are run 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 are run at regular intervals, for example, monthly. Installment transactions have a fixed duration. enum: - unscheduled - recurring - installment example: recurring customer: type: object description: Object that contains the customer's contact details and address information. properties: &ref_193 firstName: type: string description: Customer's first name. maxLength: 60 minLength: 0 example: Sarah lastName: type: string description: Customer's last name. maxLength: 60 minLength: 0 example: Hopper dateOfBirth: type: string format: date description: Customer's date of birth. The format for this value is **YYYY-MM-DD**. example: '1990-07-15' referenceNumber: type: string description: | Identifier of the transaction, also known as a customer code. For requests, you must send a value for **referenceNumber** if the customer provides one. maxLength: 48 minLength: 0 example: CustomerCode234567 billingAddress: description: Object that contains information about the address that the card is registered to. type: object title: address properties: &ref_150 address1: type: string description: Address line 1. example: 1 Example Ave. maxLength: 150 address2: type: string description: Address line 2. example: Example Address Line 2 maxLength: 150 address3: type: string description: Address line 3. example: Example Address Line 3 maxLength: 150 city: type: string description: City. example: Chicago maxLength: 50 state: type: string description: Name of the state or state abbreviation. example: Illinois maxLength: 50 country: maxLength: 2 minLength: 2 type: string description: Two-digit country code for the country that the business operates in. The format follows the [ISO-3166-1](https://www.iso.org/iso-3166-country-codes.html) standard. example: US postalCode: type: string description: Zip code or postal code. example: '60056' maxLength: 10 shippingAddress: description: Object that contains information about the customer and their shipping address. type: object properties: &ref_654 recipientName: maxLength: 50 minLength: 0 type: string description: Recipient's name. example: Sarah Hopper address: type: object title: address description: Object that contains information about the address. properties: *ref_150 contactMethods: type: array uniqueItems: true 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" items: discriminator: *ref_2 oneOf: *ref_3 notificationLanguage: type: string format: iso-639-1 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. enum: - en - fr maxLength: 2 minLength: 2 example: en source: description: "Polymorphic object that contains the payment method that we tokenized. \n\nThe value of the type parameter determines which variant you should use: \n-\t`ach` - Automated Clearing House (ACH) details\n-\t`pad` - Pre-authorized debit (PAD) details\n-\t`card` - Payment card details\n" type: object discriminator: propertyName: type mapping: ach: '#/components/schemas/achSource' pad: '#/components/schemas/padSource' card: '#/components/schemas/cardSource' oneOf: - required: &ref_153 - type - nameOnAccount - accountNumber - routingNumber type: object title: ach description: Object that contains the customer's account details. properties: &ref_154 type: type: string enum: - ach example: ach nameOnAccount: maxLength: 50 minLength: 1 type: string description: Customer's name. example: Sarah Hazel Hopper accountNumber: maxLength: 17 minLength: 4 pattern: ^[0-9]*$ type: string description: Customer's account number. example: '123456789' routingNumber: maxLength: 9 minLength: 9 pattern: ^[0-9]*$ type: string description: Routing number of the customer's account. example: '123456789' - required: &ref_155 - type - nameOnAccount - accountNumber - transitNumber - institutionNumber type: object title: pad description: Object that contains the customer's account details. properties: &ref_156 type: type: string enum: - pad example: pad nameOnAccount: maxLength: 29 minLength: 1 type: string description: Customer's name. example: Sarah Hazel Hopper accountNumber: maxLength: 12 minLength: 7 pattern: ^[0-9]*$ type: string description: Customer's account number. example: '1234567890' transitNumber: maxLength: 5 minLength: 5 pattern: ^[0-9]*$ type: string description: Five-digit code that represents the customer's banking branch. example: '76543' institutionNumber: maxLength: 3 minLength: 3 pattern: ^[0-9]*$ type: string description: Three-digit code that represents the customer's bank. example: '543' - required: &ref_157 - type - cardholderName - cardNumber type: object title: Card description: Object that contains the customer's card details. properties: &ref_158 type: description: Type of payment. type: string enum: - card example: card cardholderName: maxLength: 50 minLength: 1 type: string description: Cardholder's name. example: Sarah Hazel Hopper cardNumber: maxLength: 19 minLength: 12 type: string description: Primary account number of the customer's card. example: '4539858876047062' expiryDate: pattern: '[0-9]{4}' type: string description: Expiry date of the customer's card. example: '1230' cardType: type: string description: Card brand of the card, for example, Visa. currency: type: string description: Currency of the transaction. The value for the currency follows the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard. enum: *ref_83 debit: type: boolean description: Indicates if the card is a debit card. surcharging: required: &ref_260 - allowed type: object description: Object that contains surcharge information. Our gateway returns this object only if the merchant adds a surcharge to transactions. properties: &ref_261 allowed: type: boolean description: Indicates if the merchant can add a surcharge when the customer uses this card. example: true amount: exclusiveMinimum: 0 type: integer format: int64 description: | Surcharge amount to add to the transaction. **Note:** Our gateway returns the surcharge amount only if you include a transaction amount in the request. example: 87 percentage: exclusiveMinimum: 0 maximum: 100 type: number format: double description: Surcharge rate that the merchant configures on their account. example: 3 disclosure: type: string description: Statement that informs the customer about the surcharge fee. example: A 3% surcharge is applied to cover processing fees. token: maxLength: 19 minLength: 12 type: string description: | Token that the merchant can use in future transactions to represent the customer's payment details. The token: - Begins with the six-digit identification number **296753**. - Contains up to 12 digits. - Contains a single check digit that we calculate using the Luhn algorithm. example: '296753123456' status: type: string description: | Outcome of a security check on the status of the customer's payment card or bank account. **Note:** Depending on the merchant's account settings, this feature may be unavailable. enum: - notValidated - cvvValidated - validationFailed - issueNumberValidated - cardNumberValidated - bankAccountValidated example: cvvValidated customFields: type: array description: | Array of customField objects. items: required: *ref_129 type: object properties: *ref_130 examples: createdSecureToken: summary: Secure Token description: Secure Token value: &ref_160 secureTokenId: MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa processingTerminalId: '1234001' mitAgreement: unscheduled customer: firstName: Sarah lastName: Hopper dateOfBirth: '1990-07-15' referenceNumber: Customer-12 billingAddress: address1: 1 Example Ave. address2: Example Address Line 2 address3: Example Address Line 3 city: Chicago state: Illinois country: US postalCode: '60056' shippingAddress: recipientName: Sarah Hopper address: address1: 1 Example Ave. address2: Example Address Line 2 address3: Example Address Line 3 city: Chicago state: Illinois country: US postalCode: '60056' contactMethods: - type: email value: sarah.hopper@example.com notificationLanguage: en source: type: card cardholderName: Sarah Hazel Hopper cardNumber: 453985******7062 expiryDate: '1230' token: '296753123456' status: notValidated customFields: - name: yourCustomField value: abc123 headers: location: description: URI reference to created resource. schema: *ref_24 examples: *ref_25 '400': description: Validation error content: application/problem+json: schema: type: object properties: *ref_9 required: *ref_10 examples: validationError: summary: Bad Request description: One or more validation errors occurred value: *ref_11 idempotentKeyMissing: summary: Idempotency key missing description: Idempotency key must be supplied value: *ref_26 idempotentKeyInUse: summary: Idempotency key in use description: Idempotency key in use value: *ref_29 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '406': description: Not acceptable content: *ref_19 '409': description: Conflict content: *ref_104 '415': description: Unsupported media type content: *ref_105 '500': description: An error has occured content: *ref_14 get: tags: - Secure tokens summary: List secure tokens description: "Use this method to return a [paginated](https://docs.payroc.com/api/pagination) list of secure tokens. \n\n**Note:** If you want to view the details of a specific secure token and you have its secureTokenId, use our [Retrieve Secure Token](https://docs.payroc.com/api/schema/tokenization/secure-tokens/retrieve) method. \n\nUse query parameters to filter the list of results that we return, for example, to search for secure tokens by customer or by the first four digits of a card number. \n\nOur gateway returns information about the following for each secure token in the list: \n\n -\tPayment details that the secure token represents. \n -\tCustomer details, including shipping and billing addresses. \n -\tSecure token that you can use to carry out transactions. \n\n For each secure token, we also return the secureTokenId, which you can use to perform follow-on actions.\n" operationId: listSecureTokens parameters: - name: processingTerminalId in: path required: true description: Unique identifier that we assigned to the terminal. schema: *ref_96 examples: *ref_97 - name: secureTokenId in: query description: Unique identifier that the merchant assigned to the secure token. schema: &ref_405 maxLength: 200 minLength: 1 type: string examples: &ref_406 example: value: MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa - name: customerName in: query description: Filter by the customer's name. schema: &ref_391 maxLength: 50 minLength: 1 type: string examples: &ref_392 example: value: Sarah%20Hazel%20Hopper - name: phone in: query description: Filter by the customer's phone number. schema: &ref_407 maxLength: 15 minLength: 1 type: string examples: &ref_408 example: value: '2025550165' - name: email in: query description: Filter by the customer's email address. schema: &ref_409 maxLength: 100 minLength: 1 type: string examples: &ref_410 example: value: sarah.hopper@example.com - name: token in: query description: Filter by the token that the merchant used in a transaction to represent the customer's payment details. schema: &ref_411 maxLength: 19 minLength: 12 type: string examples: &ref_412 example: value: '296753123456' - name: first6 in: query description: Filter by the first six digits of the card number. schema: &ref_413 pattern: '[0-9]{6}' type: string examples: &ref_414 example: value: '453985' - name: last4 in: query description: Filter by the last four digits of the card or account number. schema: &ref_393 pattern: '[0-9]{4}' type: string examples: &ref_394 example: value: '7062' - name: before in: query description: | Return the previous page of results before the value that you specify. You can’t send the before parameter in the same request as the after parameter. schema: *ref_32 examples: *ref_33 - name: after in: query description: | Return the next page of results after the value that you specify. You can’t send the after parameter in the same request as the before parameter. schema: *ref_34 examples: *ref_35 - name: limit in: query description: Limit the maximum number of results that we return for each page. schema: *ref_36 examples: *ref_37 responses: '200': description: Successful request. Returns a list of secure tokens that are currently saved on the terminal. content: application/json: schema: required: &ref_657 - count - data - hasMore - limit type: object allOf: &ref_658 - type: object description: Contains the pagination properties that you use to navigate through a list of results. properties: *ref_38 - type: object properties: data: type: array description: Array of saved payment details. items: allOf: &ref_159 - required: *ref_151 type: object description: Object that contains information about the secure token. properties: *ref_152 - type: object properties: source: description: "Polymorphic object that contains the payment method that we tokenized. \n\nThe value of the type parameter determines which variant you should use: \n-\t`ach` - Automated Clearing House (ACH) details\n-\t`pad` - Pre-authorized debit (PAD) details\n-\t`card` - Payment card details\n" type: object discriminator: propertyName: type mapping: ach: '#/components/schemas/achSourceWithAccountType' pad: '#/components/schemas/padSourceWithAccountType' card: '#/components/schemas/cardSource' oneOf: - allOf: &ref_655 - required: *ref_153 type: object title: ach description: Object that contains the customer's account details. properties: *ref_154 - type: object properties: accountType: type: string description: | Indicates the customer's account type. enum: - checking - savings example: checking - allOf: &ref_656 - required: *ref_155 type: object title: pad description: Object that contains the customer's account details. properties: *ref_156 - type: object properties: accountType: type: string description: | Indicates the customer's account type. enum: - checking - savings example: checking - required: *ref_157 type: object title: Card description: Object that contains the customer's card details. properties: *ref_158 examples: paginatedResults: summary: Paginated Secure Token description: Paginated Secure Token value: &ref_940 limit: 2 count: 2 hasMore: true data: - secureTokenId: MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa processingTerminalId: '1234001' mitAgreement: unscheduled customer: firstName: Sarah lastName: Hopper dateOfBirth: '1990-07-15' referenceNumber: Customer-12 billingAddress: address1: 1 Example Ave. address2: Example Address Line 2 address3: Example Address Line 3 city: Chicago state: Illinois country: US postalCode: '60056' shippingAddress: recipientName: Sarah Hopper address: address1: 1 Example Ave. address2: Example Address Line 2 address3: Example Address Line 3 city: Chicago state: Illinois country: US postalCode: '60056' source: type: card cardholderName: Sarah Hopper cardNumber: 453985******7062 expiryDate: '1230' token: '296753123456' status: notValidated - secureTokenId: MREF_fe0d9876-cba5-432f-e10d-9cb87654a3f2e1 processingTerminalId: '1234001' mitAgreement: unscheduled customer: firstName: Sarah lastName: Hopper dateOfBirth: '1990-07-15' referenceNumber: Customer-12 billingAddress: address1: 1 Example Ave. address2: Example Address Line 2 address3: Example Address Line 3 city: Chicago state: Illinois country: US postalCode: '60056' shippingAddress: recipientName: Sarah Hopper address: address1: 1 Example Ave. address2: Example Address Line 2 address3: Example Address Line 3 city: Chicago state: Illinois country: US postalCode: '60056' source: type: card cardholderName: Sarah Hazel Hopper cardNumber: 500165******0000 expiryDate: '0328' token: '307864234567' status: notValidated customFields: - name: yourCustomField value: abc123 links: - rel: next method: get href: https://api.payroc.com/v1/processing-terminals/1234001/secure-tokens?limit=2&after=MREF_fe0d9876-cba5-432f-e10d-9cb87654a3f2e1 - rel: previous method: get href: https://api.payroc.com/v1/processing-terminals/1234001/secure-tokens?limit=2&before=MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa noActivity: summary: No records found description: Valid request, but no records match the criteria. value: *ref_55 '400': description: Invalid request content: *ref_15 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '406': description: Not acceptable content: *ref_19 '500': description: An error has occured content: *ref_14 /processing-terminals/{processingTerminalId}/secure-tokens/{secureTokenId}: get: tags: - Secure tokens summary: Retrieve secure token description: "Use this method to retrieve information about a secure token. \n\nTo retrieve a secure token, you need its secureTokenID, which you sent in the request of the [Create Secure Token](https://docs.payroc.com/api/schema/tokenization/secure-tokens/create) method. \n\n**Note:** If you don't have the secureTokenId, use our [List Secure Tokens](https://docs.payroc.com/api/schema/tokenization/secure-tokens/list) method to search for the secure token. \n\nOur gateway returns the following information about the secure token: \n\n -\tPayment details that the secure token represents. \n -\tCustomer details, including shipping and billing addresses. \n -\tSecure token that you can use to carry out transactions. \n" operationId: getSecureToken parameters: - name: processingTerminalId in: path required: true description: Unique identifier that we assigned to the terminal. schema: *ref_96 examples: *ref_97 - name: secureTokenId in: path required: true description: Unique identifier that the merchant assigned to the secure token. schema: &ref_161 maxLength: 200 minLength: 1 type: string examples: &ref_162 example: value: MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa responses: '200': description: Successful request. Returns the secure token and its related payment details. content: application/json: schema: allOf: *ref_159 examples: secureToken: summary: Secure Token description: Secure Token value: *ref_160 '400': description: Invalid request content: *ref_15 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '404': description: Resource not found content: *ref_18 '406': description: Not acceptable content: *ref_19 '500': description: An error has occured content: *ref_14 patch: tags: - Secure tokens summary: Partially update secure token description: | Use this method to partially update a secure token. Structure your request to follow the [RFC 6902](https://datatracker.ietf.org/doc/html/rfc6902) standard. To update a secure token, you need its secureTokenId, which you sent in the request of the [Create Secure Token](https://docs.payroc.com/api/schema/tokenization/secure-tokens/create) method. **Note:** If you don't have the secureTokenId, use our [List Secure Tokens](https://docs.payroc.com/api/schema/tokenization/secure-tokens/list) method to search for the payment. You can update all of the properties of the secure token, except the following: - processingTerminalId - type - token - status - source/Card - type - cardNumber - cardType - currency - debit - surcharging - source/ACH account - accountNumber - routingNumber - source/PAD account - type - accountNumber - transitNumber operationId: updateSecureToken parameters: - name: Idempotency-Key in: header required: true 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). schema: *ref_22 examples: *ref_23 - name: processingTerminalId in: path required: true description: Unique identifier that we assigned to the terminal. schema: *ref_96 examples: *ref_97 - name: secureTokenId in: path required: true description: Unique identifier that the merchant assigned to the secure token. schema: *ref_161 examples: *ref_162 requestBody: required: true content: application/json: schema: type: array description: A JSON Patch document as defined by RFC 6902. items: *ref_101 example: *ref_102 examples: patchSecureTokenRealistic: summary: Update secure token description: | Update the customer's payment details that are represented by the secure token. Structure your request to follow the [RFC 6902](https://datatracker.ietf.org/doc/html/rfc6902) standard. value: &ref_942 - op: replace path: /customer/lastName value: Reed - op: replace path: /shippingAddress/recipientName value: Sarah Reed - op: replace path: /source/cardDetails/cardholderName value: Sarah Reed patchOperations: summary: Example patch operations that apply the RFC 6902 standard description: | Example patch operations that apply the RFC 6902 standard. value: *ref_103 responses: '200': description: Successful request. We updated the customer's payment details. content: application/json: schema: required: *ref_151 type: object description: Object that contains information about the secure token. properties: *ref_152 examples: secureToken: summary: Secure Token description: Secure Token value: *ref_160 '400': description: Validation error content: application/problem+json: schema: type: object properties: *ref_9 required: *ref_10 examples: validationError: summary: Bad Request description: One or more validation errors occurred value: *ref_11 idempotentKeyMissing: summary: Idempotency key missing description: Idempotency key must be supplied value: *ref_26 idempotentKeyInUse: summary: Idempotency key in use description: Idempotency key in use value: *ref_29 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '404': description: Resource not found content: *ref_18 '406': description: Not acceptable content: *ref_19 '409': description: Conflict content: *ref_104 '415': description: Unsupported media type content: *ref_105 '500': description: An error has occured content: *ref_14 delete: tags: - Secure tokens summary: Delete secure token description: | Use this method to delete a secure token and its related payment details from our vault. To delete a secure token, you need its secureTokenId, which you sent in the request of the [Create Secure Token](https://docs.payroc.com/api/schema/tokenization/secure-tokens/create) method. **Note:** If you don’t have the secureTokenId, use our [List Secure Tokens](https://docs.payroc.com/api/schema/tokenization/secure-tokens/list) method to search for the secure token. When you delete a secure token, you can’t recover it, and you can’t reuse its identifier for a new token. operationId: deleteSecureToken parameters: - name: processingTerminalId in: path required: true description: Unique identifier that we assigned to the terminal. schema: *ref_96 examples: *ref_97 - name: secureTokenId in: path required: true description: Unique identifier that the merchant assigned to the secure token. schema: *ref_161 examples: *ref_162 responses: '204': description: Successful request. We deleted the secure token. '400': description: Invalid request content: *ref_15 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '404': description: Resource not found content: *ref_18 '500': description: An error has occured content: *ref_14 /processing-terminals/{processingTerminalId}/secure-tokens/{secureTokenId}/update-account: post: tags: - Secure tokens summary: Update account details description: | Use this method to update a secure token if you have a single-use token from Hosted Fields. **Note:** If you don't have a single-use token, you can update saved payment details with our [Update Secure Token](https://docs.payroc.com/api/resources#updateSecureToken) method. For more information about our two options to update a secure token, go to [Update saved payment details](https://docs.payroc.com/guides/take-payments/update-saved-payment-details). operationId: accountUpdate parameters: - name: Idempotency-Key in: header required: true 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). schema: *ref_22 examples: *ref_23 - name: processingTerminalId in: path required: true description: Unique identifier that we assigned to the terminal. schema: *ref_96 examples: *ref_97 - name: secureTokenId in: path required: true description: Unique identifier that the merchant assigned to the secure token. schema: *ref_161 examples: *ref_162 requestBody: description: Polymorphic object that contains information about the single-use token. content: application/json: schema: description: Polymorphic object that contains information about the single-use token. discriminator: &ref_687 propertyName: type mapping: singleUseToken: '#/components/schemas/singleUseTokenAccountUpdate' oneOf: &ref_688 - required: &ref_685 - type - token type: object description: Object that contains the token. properties: &ref_686 type: type: string enum: - singleUseToken example: singleUseToken description: Type of token. token: description: Single-use token that the gateway assigned to the payment details. maxLength: 128 minLength: 128 type: string example: abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890 examples: accountUpdate: summary: Update account details description: Account update request by single use token value: &ref_943 type: singleUseToken token: abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890 required: true responses: '200': description: Successful request. We updated the payment details represented by the secure token. content: application/json: schema: required: *ref_151 type: object description: Object that contains information about the secure token. properties: *ref_152 examples: accountUpdateResponse: summary: Secure Token description: Secure Token value: *ref_160 '400': description: Invalid request content: *ref_15 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '404': description: Resource not found content: *ref_18 '406': description: Not acceptable content: *ref_19 '409': description: Conflict content: *ref_104 '413': description: Payload too large content: &ref_343 application/problem+json: schema: type: object properties: &ref_537 type: type: string description: URI reference identifying the problem type example: https://docs.payroc.com/api/errors#payload-too-large title: type: string description: Short description of the issue. example: Payload too large status: type: integer description: Http status code example: 413 detail: type: string description: Explanation of the problem example: The payload submitted is too large. required: &ref_538 - type - title - status - detail examples: payloadTooLarge: summary: Payload too large description: The payload submitted is too large value: &ref_944 type: https://docs.payroc.com/api/errors#payload-too-large title: Payload too large status: 413 detail: The payload submitted is too large '415': description: Unsupported media type content: *ref_105 '500': description: An error has occured content: *ref_14 /processing-terminals/{processingTerminalId}/single-use-tokens: post: tags: - Single use tokens summary: Create single use token description: | Use this method to create a single-use token that represents a customer’s payment details. A single-use token expires after 30 minutes and merchants can use them only once. **Note:** To create a reusable permanent token, go to [Create Secure Token](https://docs.payroc.com/api/schema/tokenization/secure-tokens/create). In the request, send the customer’s payment details. If the request is successful, our gateway returns a token that you can use in a follow-on action, for example, [run a sale](https://docs.payroc.com/api/schema/card-payments/payments/create). operationId: createSingleUseToken parameters: - name: Idempotency-Key in: header required: true 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). schema: *ref_22 examples: *ref_23 - name: processingTerminalId in: path required: true description: Unique identifier that our gateway assigned to the terminal. schema: &ref_415 maxLength: 50 minLength: 4 type: string examples: &ref_416 example: value: '1234001' requestBody: content: application/json: schema: required: &ref_689 - channel - source type: object properties: &ref_690 channel: type: string description: Channel that the merchant used to receive the payment details. enum: - pos - web - moto example: web operator: maxLength: 50 minLength: 1 type: string description: Operator who initiated the request. example: Jane source: description: "Polymorphic object that contains the payment method to tokenize. \n\nThe value of the type parameter determines which variant you should use: \n-\t`ach` - Automated Clearing House (ACH) details\n-\t`pad` - Pre-authorized debit (PAD) details\n-\t`card` - Payment card details\n" type: object discriminator: propertyName: type mapping: ach: '#/components/schemas/achPayload' pad: '#/components/schemas/padPayload' card: '#/components/schemas/cardPayload' oneOf: - required: *ref_163 type: object writeOnly: true title: ach description: Object that contains information about the payment details for the customer’s automated clearing house (ACH) transactions. properties: *ref_164 - required: *ref_165 type: object writeOnly: true title: pad description: Object that contains information about the payment details for the customer’s preauthorized electronic debit (PAD) transactions. properties: *ref_166 - required: *ref_167 type: object writeOnly: true title: card description: Object that contains information about the customer’s payment card. properties: *ref_168 examples: createSingleUseToken: summary: Create single-use token description: Create a single-use token. The token expires after 30 minutes. value: &ref_945 channel: web operator: Jane source: type: card cardDetails: entryMethod: keyed cardholderName: Sarah Hazel Hopper keyedData: dataFormat: plainText cardNumber: '4539858876047062' expiryDate: '1230' cvv: '234' required: true responses: '201': description: Successful request. We created the single-use token. content: application/json: schema: required: &ref_691 - processingTerminalId - token - expiresAt - source type: object properties: &ref_692 processingTerminalId: maxLength: 50 minLength: 4 type: string readOnly: true description: Unique identifier that we assigned to the terminal. example: '1234001' operator: maxLength: 50 minLength: 0 type: string writeOnly: true description: Operator who initiated the request. example: Jane paymentMethod: type: object description: Polymorphic object that contains payment card details. writeOnly: true discriminator: propertyName: type mapping: card: '#/components/schemas/cardPayload' oneOf: - required: *ref_167 type: object writeOnly: true title: card description: Object that contains information about the customer’s payment card. properties: *ref_168 token: maxLength: 128 minLength: 128 type: string readOnly: true description: | Unique identifier that our gateway assigned to the payment details. **Note:** Merchants can use the token with other terminals linked to their account. example: fa2e9e51bc5265a33a5ca41449524d53d1def596ffd8c0904f222183a71a65cdb58835120a65196a48a6375abc4deafe2b7e948689ab9d6aba919e860f32e247 expiresAt: type: string format: date-time readOnly: true description: Date and time that the token expires. We return this value in the [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format. example: '2024-07-02T16:00:00Z' source: description: "Polymorphic object that contains the payment method that we tokenized. \n\nThe value of the type parameter determines which variant you should use: \n-\t`ach` - Automated Clearing House (ACH) details\n-\t`pad` - Pre-authorized debit (PAD) details\n-\t`card` - Payment card details\n" type: object discriminator: propertyName: type mapping: ach: '#/components/schemas/achSource' pad: '#/components/schemas/padSource' card: '#/components/schemas/cardSource' oneOf: - required: *ref_153 type: object title: ach description: Object that contains the customer's account details. properties: *ref_154 - required: *ref_155 type: object title: pad description: Object that contains the customer's account details. properties: *ref_156 - required: *ref_157 type: object title: Card description: Object that contains the customer's card details. properties: *ref_158 examples: createSingleUseToken: summary: Create single-use token description: Create a single-use token. The token expires after 30 minutes. value: &ref_946 processingTerminalId: '1234001' token: fa2e9e51bc5265a33a5ca41449524d53d1def596ffd8c0904f222183a71a65cdb58835120a65196a48a6375abc4deafe2b7e948689ab9d6aba919e860f32e247 expiresAt: '2024-08-05T19:50:05.723+02:00' source: type: card cardholderName: Sarah Hazel Hopper cardNumber: 453985******7062 expiryDate: '1230' cardType: Visa Credit country: US currency: USD debit: false headers: location: description: URI reference to created resource. schema: *ref_24 examples: *ref_25 '400': description: Validation error content: application/problem+json: schema: type: object properties: *ref_9 required: *ref_10 examples: validationError: summary: Bad Request description: One or more validation errors occurred value: *ref_11 idempotentKeyMissing: summary: Idempotency key missing description: Idempotency key must be supplied value: *ref_26 idempotentKeyInUse: summary: Idempotency key in use description: Idempotency key in use value: *ref_29 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '406': description: Not acceptable content: *ref_19 '409': description: Conflict content: *ref_104 '415': description: Unsupported media type content: *ref_105 '500': description: An error has occured content: *ref_14 /processing-terminals/{processingTerminalId}/hosted-fields-sessions: post: tags: - Hosted Fields summary: Create Hosted Fields session description: | Use this method to create a Hosted Fields session token. You need to generate a new session token each time you load Hosted Fields on a webpage. In your request, you need to indicate whether the merchant is using Hosted Fields to run a sale, save payment details, or update saved payment details. In the response, our gateway returns the session token and the time that it expires. You need the session token when you configure the JavaScript for Hosted Fields. For more information about adding Hosted Fields to a webpage, go to [Hosted Fields](https://docs.payroc.com/guides/take-payments/hosted-fields). operationId: createSession parameters: - name: Idempotency-Key in: header required: true 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). schema: *ref_22 examples: *ref_23 - name: processingTerminalId in: path required: true description: Unique identifier that we assigned to the terminal. schema: *ref_96 examples: *ref_97 requestBody: content: application/json: schema: required: &ref_693 - libVersion - scenario type: object title: Hosted Fields Initialization description: Object that contains information about Hosted Fields initialization request. properties: &ref_694 libVersion: type: string pattern: ^\d{1,2}.\d{1,2}.\d{1,2}(?:-beta)?.\d+$ description: | Version of the Hosted Fields JavaScript library that you are using. The current production version is `1.6.0.172441`. example: 1.6.0.172441 scenario: type: string enum: - payment - tokenization description: | Indicates if a merchant wants to take a payment or tokenize a customer's payment details: - `payment` - The merchant wants to run a sale or run a sale and tokenize in the same transaction. - `tokenization` - The merchant wants to save the customer's payment details to take a payment later or to update a customer's payment details that they've already saved. example: payment secureTokenId: maxLength: 200 minLength: 1 type: string description: | Unique identifier that represents a customer's payment details. If a merchant wants to update a customer's payment details that are linked to a secure token, include the secureTokenId in your request. example: MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa examples: createSessionRequest: summary: Create session request description: Create session request. value: &ref_947 libVersion: 1.1.0.123456 scenario: payment required: true responses: '201': description: Successful request. We created the session and returned a session token. content: application/json: schema: required: &ref_695 - processingTerminalId - token - expiresAt type: object properties: &ref_696 processingTerminalId: type: string description: Unique identifier that we assigned to the terminal. token: type: string description: | Token that our gateway assigned to the Hosted Fields session. Include this session token in the config file for Hosted Fields. The session token expires after 10 minutes. example: abcdef1234567890abcdef1234567890 expiresAt: type: string format: date-time readOnly: true description: Date and time that the token expires. We return this value in the [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format. example: '2025-07-02T15:30:00.000+02:00' examples: createSessionResponse: summary: Create session response description: Create session response. value: &ref_948 processingTerminalId: '1234001' token: abcdef1234567890abcdef1234567890 expiresAt: '2025-07-02T15:30:00.000+02:00' headers: location: description: URI reference to created resource. schema: *ref_24 examples: *ref_25 '400': description: Validation error content: application/problem+json: schema: type: object properties: *ref_9 required: *ref_10 examples: validationError: summary: Bad Request description: One or more validation errors occurred value: *ref_11 idempotentKeyMissing: summary: Idempotency key missing description: Idempotency key must be supplied value: *ref_26 idempotentKeyInUse: summary: Idempotency key in use description: Idempotency key in use value: *ref_29 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '406': description: Not acceptable content: *ref_19 '409': description: Conflict content: *ref_104 '415': description: Unsupported media type content: *ref_105 '500': description: An error has occured content: *ref_14 /processing-terminals/{processingTerminalId}/apple-pay-sessions: post: tags: - Apple Pay session summary: Start Apple Pay session description: | Use this method to start an Apple Pay session for your merchant. In the response, we return the startSessionObject that you send to Apple when you retrieve the cardholder's encrypted payment details. **Note:** For more information about how to integrate with Apple Pay, go to [Apple Pay](https://docs.payroc.com/guides/take-payments/apple-pay). operationId: applePaySessions parameters: - name: processingTerminalId in: path required: true description: Unique identifier that we assigned to the terminal. schema: *ref_96 examples: *ref_97 requestBody: content: application/json: schema: required: &ref_697 - appleDomainId - appleValidationUrl type: object properties: &ref_698 appleDomainId: type: string description: Unique appleDomainId of the merchant's domain that we assigned when you added their domain to our Self-Care Portal. example: DUHDZJHGYY appleValidationUrl: type: string description: Validation URL from the Apple Pay JS API. example: https://apple-pay-gateway.apple.com/paymentservices/startSession examples: applePaySessions: summary: Apple Pay session description: Start a session with Apple to accept a payment with Apple Pay. value: &ref_949 appleDomainId: DUHDZJHGYY appleValidationUrl: https://apple-pay-gateway.apple.com/paymentservices/startSession required: true responses: '200': description: Successful request. We started the Apple Pay session. content: application/json: schema: required: &ref_699 - startSessionResponse type: object properties: &ref_700 startSessionResponse: type: string description: | Object that Apple returns when they start the merchant's Apple Pay session. Send the content in this object to Apple to retrieve the cardholder's encrypted payment details. example: | { "epochTimestamp": 1736264582447, "expiresAt": 1736268182447, "merchantSessionIdentifier": "SSHE464E2B91B714F18BFD19D46D0F582BF_916523AAED1343F5BC5815E12BEE9250AFFDC1A17C46B0DE5A943F0F94927C24", "nonce": "e5775127", "merchantIdentifier": "BFB110EE83BE2AF4AA7468926C926CCFC57F4A541CCE6E7F3BEFD05002ECE503", "domainName": "store.com", "displayName": "Store One", "signature": "a1b1c012345678a000b000c0012345d0e0f010g10061a031i001j071k0a1b0c1d0e1234567890120f1g0h1i0j1k0a1b0123451c012d0e1f0g1h0i1j123k1a1b1c1d1e1f1g123h1i1j1k1a1b1c1d1e1f1g123h123i1j123k12340a120a12345b012c0123012d0d1e0f1g0h1i123j123k10000", "operationalAnalyticsIdentifier": "Store One:BFB110EE83BE2AF4AA7468926C926CCFC57F4A541CCE6E7F3BEFD05002ECE503", "retries": 0, "pspId": "17D4AAA8D9357D26D771ABA0DAA0B9D3BB462AD1585492E1FE688AF8BB9558E5" } examples: applePayResponseSession: summary: Apple Pay session response description: Wrapper for the content that Apple returns after starting the Apple Pay session. value: &ref_950 startSessionResponse: | { "epochTimestamp": 1736264582447, "expiresAt": 1736268182447, "merchantSessionIdentifier": "SSHE464E2B91B714F18BFD19D46D0F582BF_916523AAED1343F5BC5815E12BEE9250AFFDC1A17C46B0DE5A943F0F94927C24", "nonce": "e5775127", "merchantIdentifier": "BFB110EE83BE2AF4AA7468926C926CCFC57F4A541CCE6E7F3BEFD05002ECE503", "domainName": "store.com", "displayName": "Store One", "signature": "a1b1c012345678a000b000c0012345d0e0f010g10061a031i001j071k0a1b0c1d0e1234567890120f1g0h1i0j1k0a1b0123451c012d0e1f0g1h0i1j123k1a1b1c1d1e1f1g123h1i1j1k1a1b1c1d1e1f1g123h123i1j123k12340a120a12345b012c0123012d0d1e0f1g0h1i123j123k10000", "operationalAnalyticsIdentifier": "Store One:BFB110EE83BE2AF4AA7468926C926CCFC57F4A541CCE6E7F3BEFD05002ECE503", "retries": 0, "pspId": "17D4AAA8D9357D26D771ABA0DAA0B9D3BB462AD1585492E1FE688AF8BB9558E5" } '400': description: Validation error content: application/problem+json: schema: type: object properties: *ref_9 required: *ref_10 examples: validationError: summary: Bad Request description: One or more validation errors occurred value: *ref_11 '500': description: An error has occured content: *ref_14 /payments: post: tags: - Payments summary: Create payment operationId: payment description: "Use this method to run a sale or a pre-authorization with a customer's payment card. \n\nIn the response, our gateway returns information about the card payment and a paymentId, which you need for the following methods:\n\n-\t[Retrieve payment](https://docs.payroc.com/api/schema/card-payments/payments/retrieve) - View the details of the card payment.\n-\t[Adjust payment](https://docs.payroc.com/api/schema/card-payments/payments/adjust) - Update the details of the card payment.\n-\t[Capture payment](https://docs.payroc.com/api/schema/card-payments/payments/capture) - Capture the pre-authorization.\n-\t[Reverse payment](https://docs.payroc.com/api/schema/card-payments/refunds/reverse) - Cancel the card payment if it's in an open batch.\n-\t[Refund payment](https://docs.payroc.com/api/schema/card-payments/refunds/create-referenced-refund) - Run a referenced refund to return funds to the payment card.\n\n**Payment methods** \n\n- **Cards** - Credit, debit, and EBT\n- **Digital wallets** - [Apple Pay®](https://docs.payroc.com/guides/take-payments/apple-pay) and [Google Pay®](https://docs.payroc.com/guides/take-payments/google-pay) \n- **Tokens** - Secure tokens and single-use tokens\n\n**Features** \n\nOur Create Payment method also supports the following features: \n\n- [Repeat payments](https://docs.payroc.com/guides/take-payments/repeat-payments/use-your-own-software) - Run multiple payments as part of a payment schedule that you manage with your own software. \n- **Offline sales** - Run a sale or a pre-authorization if the terminal loses its connection to our gateway. \n- [Tokenization](https://docs.payroc.com/guides/take-payments/save-payment-details) - Save card details to use in future transactions. \n- [3-D Secure](https://docs.payroc.com/guides/take-payments/3-d-secure) - Verify the identity of the cardholder. \n- [Custom fields](https://docs.payroc.com/guides/take-payments/add-custom-fields) - Add your own data to a payment. \n- **Tips** - Add tips to the card payment. \n- **Taxes** - Add local taxes to the card payment. \n- **Surcharging** - Add a surcharge to the card payment. \n- **Dual pricing** - Offer different prices based on payment method, for example, if you use our RewardPay Choice pricing program. \n" parameters: - name: Idempotency-Key in: header required: true 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). schema: *ref_22 examples: *ref_23 requestBody: content: application/json: schema: required: &ref_722 - channel - order - paymentMethod - processingTerminalId type: object properties: &ref_723 channel: type: string description: Channel that the merchant used to receive the payment details. enum: - pos - web - moto example: web processingTerminalId: maxLength: 50 minLength: 4 type: string description: Unique identifier that we assigned to the terminal. example: '1234001' operator: maxLength: 50 minLength: 0 type: string description: Operator who ran the transaction. example: Jane order: type: object description: Object that contains information about the payment. allOf: &ref_719 - required: &ref_187 - amount - currency - orderId type: object description: Object that contains information about the payment. allOf: &ref_188 - required: &ref_218 - amount - currency - orderId type: object description: Object that contains details about the transaction. properties: &ref_219 orderId: maxLength: 24 minLength: 1 type: string description: Unique identifier that the merchant assigns to the transaction. example: OrderRef6543 dateTime: type: string format: date-time readOnly: true 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. example: '2024-07-02T15:30:00Z' description: maxLength: 1024 minLength: 0 type: string description: Description of the transaction. example: 'Pizza Doe #1234 - Dinner' amount: type: integer format: int64 description: Total amount of the transaction. The value is in the currency’s lowest denomination, for example, cents. example: 2899 currency: type: string description: Currency of the transaction. The value for the currency follows the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard. enum: *ref_83 - type: object properties: orderId: maxLength: 24 minLength: 1 type: string description: A unique identifier assigned by the merchant. example: OrderRef6543 dateTime: type: string format: date-time readOnly: true description: Date and time that the processor processed the transaction. Our gateway returns this value in the ISO 8601 format. example: '2024-07-02T15:30:00Z' description: maxLength: 256 minLength: 1 type: string description: Description of the transaction. example: Large Pepperoni Pizza amount: type: integer format: int64 description: Total amount of the transaction. The value is in the currency’s lowest denomination, for example, cents. example: 4999 currency: type: string description: Currency of the transaction. The value for the currency follows the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard. enum: *ref_83 dccOffer: required: &ref_227 - fxAmount - fxCurrency - fxRate - markup type: object 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). properties: &ref_228 accepted: type: boolean writeOnly: true description: Indicates if the cardholder accepted DCC offer. example: true offerReference: type: string description: Unique identifier of the DCC offer. example: DCC123456789 fxAmount: type: integer format: int64 description: Amount in the cardholder’s currency in the currency’s lowest denomination, for example, cents. example: 3955 fxCurrency: 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. allOf: - type: string description: Currency of the transaction. The value for the currency follows the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard. enum: *ref_83 fxCurrencyCode: maxLength: 3 minLength: 3 type: string readOnly: true description: Three-digit currency code for the card. This code follows the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard. example: CAD fxCurrencyExponent: type: integer readOnly: true 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. format: int32 example: 2 fxRate: type: number description: Foreign exchange rate for the card's currency. format: double example: 1.37 markup: type: number description: Markup percentage rate that the DCC provider applies to the foreign exchange rate. format: double example: 3.5 markupText: type: string readOnly: true description: Supporting text for the markup rate. example: 3.5% mark-up applied. provider: type: string readOnly: true description: Name of the DCC provider. example: DCC Provider Inc. source: type: string readOnly: true description: Source that the DCC provider used to get the foreign exchange rates. example: European Central Bank standingInstructions: required: &ref_702 - processingModel - sequence type: object description: If you don't use our Subscriptions mechanism, include this section to configure your standing/recurring orders. properties: &ref_703 sequence: type: string description: Position of the transaction in the payment plan sequence. enum: - first - subsequent example: first processingModel: type: string description: | Indicates the type of payment instruction. - 'unscheduled' – The payment is not part of a regular billing cycle. - 'recurring' – The payment is part of a regular billing cycle with no end date. - 'installment' – The payment is part of a regular billing cycle with an end date. enum: - unscheduled - recurring - installment example: recurring referenceDataOfFirstTxn: description: Object that contains information about the initial payment for the payment instruction. type: object properties: &ref_701 paymentId: maxLength: 10 minLength: 10 type: string description: | Unique identifier of the first payment. **Note:** We recommend that you always send a value for **paymentId**. example: M2MJOG6O2Y cardSchemeReferenceId: maxLength: 64 minLength: 1 type: string description: Identifier that the card brand assigns to the payment instruction. example: ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890 - type: object properties: breakdown: required: &ref_216 - subtotal type: object description: Object that contains information about the breakdown of the transaction. allOf: &ref_217 - type: object allOf: &ref_717 - required: &ref_189 - subtotal type: object description: Object that contains information about the breakdown of the transaction. properties: &ref_190 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. example: 2899 cashbackAmount: type: integer format: int64 description: Amount of cashback for the transaction. example: 0 tip: description: Object that contains tip information for the transaction. required: &ref_211 - type type: object properties: &ref_212 type: type: string 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. enum: - percentage - fixedAmount example: percentage mode: type: string readOnly: true 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. enum: - prompted - adjusted example: prompted amount: exclusiveMinimum: 0 type: integer format: int64 description: | If the value for type is `fixedAmount`, this value is the tip amount in the currency's lowest denomination, for example, cents. example: 500 percentage: maximum: 100 exclusiveMinimum: 0 type: number format: double description: If the value for type is `percentage`, this value is the tip as a percentage. example: 10 surcharge: description: Object that contains surcharge information for the transaction. type: object properties: *ref_169 dualPricing: description: Object that contains dual pricing information for the transaction. required: &ref_706 - offered type: object properties: &ref_707 offered: type: boolean description: Indicates if the merchant offered dual pricing to the customer. example: false 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. required: &ref_704 - applied - rate - amount type: object readOnly: true properties: &ref_705 applied: type: boolean 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. default: false example: true rate: type: number format: double description: | If the customer used a card to pay for the transaction, this value indicates the percentage that our gateway added to the transaction amount. **Note:** Our gateway returns a value for **rate** only if the value for **applied** in the request is `true`. maximum: 100 exclusiveMinimum: 0 example: 2.5 amount: type: integer format: int64 description: | If the customer used a card to pay for the transaction, this value indicates the amount that our gateway added to the transaction amount. This value is in the currency’s lowest denomination, for example, cents. **Note:** Our gateway returns a value for **amount** only if the value for **applied** in the request is `true`. exclusiveMinimum: 0 example: 75 alternativeTender: type: string 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. enum: - card - cash - bankTransfer example: card - type: object properties: taxes: type: array description: "Array of polymorphic tax objects, which contain information about a tax. \n\nThe value of the type parameter determines which variant you should use: \n-\t`amount` - Tax is a fixed amount.\n-\t`rate` - Tax is a percentage.\n" items: type: object description: "Polymorphic object that contains tax details. \n\nThe value of the type parameter determines which variant you should use: \n-\t`amount` - Tax is a fixed amount.\n-\t`rate` - Tax is a percentage.\n" discriminator: &ref_174 propertyName: type mapping: amount: '#/components/schemas/taxAmount' rate: '#/components/schemas/taxRate' oneOf: &ref_175 - type: object required: &ref_715 - name - amount - type properties: &ref_716 type: type: string enum: - amount default: amount description: Indicates that the tax is an amount. amount: type: integer format: int64 description: Tax amount for the transaction. The value is in the currency's lowest denomination, for example, cents. minimum: 0 exclusiveMinimum: 0 example: 190 name: type: string description: Name of the tax. maxLength: 64 minLength: 1 example: Sales Tax - type: object required: *ref_170 properties: *ref_171 - type: object properties: 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. example: 0 freightAmount: type: integer format: int64 description: | Amount for shipping in the currency's lowest denomination, for example, cents. example: 0 convenienceFee: required: *ref_172 type: object readOnly: true description: Object that contains information about the convenience fee for the transaction. properties: *ref_173 items: type: array description: Array of objects that contain information about each item that the customer purchased. items: description: Array of 'lineItem' objects. Each object contains information about the items in the transaction. type: object allOf: &ref_718 - required: &ref_191 - quantity - unitPrice type: object description: List of line items. properties: &ref_192 commodityCode: maxLength: 45 minLength: 0 type: string description: Commodity code of the item. example: 5812-0111 productCode: maxLength: 45 minLength: 0 type: string description: Product code of the item. example: PZA-001-LG description: maxLength: 250 minLength: 0 type: string description: Description of the item. example: Large Pepperoni Pizza unitOfMeasure: type: string 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). example: QAN enum: &ref_709 - 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 unitPrice: type: number description: Price of each unit. exclusiveMinimum: 0 example: 2709 quantity: type: number format: double exclusiveMinimum: 0 description: Number of units. example: 1 discountRate: type: number format: double description: Discount rate that the merchant applies to the item. exclusiveMinimum: 0 example: 5 - type: object properties: taxes: type: array description: Array of objects that contain information about each tax that applies to the item. items: type: object description: "Polymorphic object that contains tax details. \n\nThe value of the type parameter determines which variant you should use: \n-\t`amount` - Tax is a fixed amount.\n-\t`rate` - Tax is a percentage.\n" discriminator: *ref_174 oneOf: *ref_175 customer: type: object description: Object that contains the customer's contact details and address information. properties: *ref_176 ipAddress: required: *ref_177 type: object writeOnly: true description: Object that contains the IP address of the device that sent the request. properties: *ref_178 paymentMethod: type: object description: "Polymorphic object that contains payment details. \n\nThe value of the type parameter determines which variant you should use: \n-\t`card` - Payment card details\n-\t`secureToken` - Secure token details\n-\t`digitalWallet` - Digital wallet details\n-\t`singleUseToken` - Single-use token details\n" discriminator: propertyName: type mapping: card: '#/components/schemas/cardPayload' secureToken: '#/components/schemas/secureTokenPayload' digitalWallet: '#/components/schemas/digitalWalletPayload' singleUseToken: '#/components/schemas/singleUseTokenPayload' oneOf: - required: *ref_167 type: object writeOnly: true title: card description: Object that contains information about the customer’s payment card. properties: *ref_168 - required: *ref_179 type: object writeOnly: true title: secureToken description: Object that contains information about the secure token that represents the customer’s payment details. properties: *ref_180 - required: &ref_258 - type - encryptedData - serviceProvider type: object writeOnly: true title: digitalWallet description: Object that contains information about the payment details in the customer’s digital wallet. properties: &ref_259 type: type: string description: Method that the terminal used to take the payment. enum: - digitalWallet accountType: type: string description: | Indicates the customer’s account type. **Note:** Send a value for accountType only for bank account details. enum: - checking - savings example: checking serviceProvider: type: string description: | Provider of the digital wallet. Send one of the following values: - `apple` - For more information about how to integrate with Apple Pay, go to [Apple Pay®](https://docs.payroc.com/guides/take-payments/apple-pay). - `google` - For more information about how to integrate with google Pay, go to [Google Pay®](https://docs.payroc.com/guides/take-payments/google-pay). enum: - apple - google cardholderName: maxLength: 50 minLength: 0 type: string description: Cardholder’s name. encryptedData: maxLength: 20480 minLength: 128 type: string description: Encrypted data of the digital wallet. - required: *ref_181 type: object writeOnly: true title: singleUseToken description: Object that contains information about the single-use token, which represents the customer’s payment details. properties: *ref_182 threeDSecure: type: object description: "Polymorphic object that contains authentication information from 3-D Secure. \n\nThe value of the serviceProvider parameter determines which variant you should use: \n-\t`gateway` - Use our gateway to run a 3-D Secure check.\n-\t`thirdParty` - Use a third party to run a 3-D Secure check.\n" discriminator: propertyName: serviceProvider mapping: gateway: '#/components/schemas/gatewayThreeDSecure' thirdParty: '#/components/schemas/thirdPartyThreeDSecure' oneOf: - required: *ref_183 type: object title: gateway description: Object that contains the 3-D Secure information from our gateway. properties: *ref_184 - required: *ref_185 type: object title: thirdParty description: Object that contains the 3-D Secure information from a third party. properties: *ref_186 credentialOnFile: type: object description: Object that contains information about saving the customer’s payment details. properties: &ref_220 externalVault: type: boolean default: false description: Indicates if the merchant uses a third-party vault to store the customer’s payment details. example: false tokenize: type: boolean description: Indicates if our gateway should tokenize the customer’s payment details as part of the transaction. example: true secureTokenId: maxLength: 200 minLength: 0 type: string 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**, our gateway generates a unique identifier for the token. example: MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa mitAgreement: type: string description: | Indicates how the merchant can use the customer’s card details, as agreed by the customer: - `unscheduled` - Transactions for a fixed or variable amount that are run at a certain pre-defined event. - `recurring` - Transactions for a fixed amount that are run 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 are run 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. enum: - unscheduled - recurring - installment example: recurring offlineProcessing: required: &ref_720 - operation type: object description: Object that contains information about the transaction if the merchant ran it when the terminal was offline. properties: &ref_721 operation: type: string description: Status of the transaction. enum: - offlineDecline - offlineApproval - deferredAuthorization example: offlineApproval approvalCode: maxLength: 48 minLength: 0 type: string description: Approval code for the transaction from the processor. example: OK3 dateTime: type: string format: date-time description: Date and time that the merchant ran the transaction. The date follows the ISO 8601 standard. example: '2024-07-02T15:30:00Z' 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. example: true 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**. example: false customFields: type: array description: | Array of customField objects. items: required: *ref_129 type: object properties: *ref_130 examples: paymentRequest: summary: Card Payment description: Payment value: &ref_952 channel: web processingTerminalId: '1234001' operator: Jane order: orderId: OrderRef6543 description: Large Pepperoni Pizza currency: USD amount: 4999 customer: firstName: Sarah lastName: Hopper billingAddress: address1: 1 Example Ave. address2: Example Address Line 2 address3: Example Address Line 3 city: Chicago state: Illinois country: US postalCode: '60056' shippingAddress: recipientName: Sarah Hopper address: address1: 1 Example Ave. address2: Example Address Line 2 address3: Example Address Line 3 city: Chicago state: Illinois country: US postalCode: '60056' paymentMethod: type: card cardDetails: entryMethod: keyed keyedData: dataFormat: plainText device: model: paxA80 serialNumber: WPC202833004712 expiryDate: '1230' cardNumber: '4539858876047062' customFields: - name: yourCustomField value: abc123 applePaySaleRequest: summary: Apple Pay Payment value: &ref_953 channel: web processingTerminalId: '1234001' operator: Jane order: orderId: 1234567890W description: Card Transaction (APPLE) amount: 4999 currency: USD paymentMethod: type: digitalWallet serviceProvider: apple encryptedData: 7b2262696c6c696e67436f6e74616374223a7b2266616d696c794e616d65223a22222c22676976656e4e616d65223a22222c2270686f6e6574696346616d696c794e616d65223a22222c2270686f6e65746963476976656e4e616d65223a22227d2c227368697070696e67436f6e74616374223a7b22656d61696c41646472657373223a227465737440646f6d61696e2e636f6d222c2266616d696c794e616d65223a22222c22676976656e4e616d65223a22222c2270686f6e6574696346616d696c794e616d65223a22222c2270686f6e65746963476976656e4e616d65223a22227d2c22746f6b656e223a7b227061796d656e7444617461223a7b2264617461223a2259314b37626731573479755568587473335941627a6150756c384d31795057304c724637734e2f70415950456d3871647969716c6257777356792b7732334c666c74344e6932525a684c2f6a52727563356f69496235537437763248543739682b74702f78517838496b6a5631485354594d747156644c6a413977686379774f654f70326575556d306e56386b50726569564273726a596c355931437a30576371495648595134424e737a4b5876675063686a497a6f4d4b456336425650744c7335777654667a434b51574a496a646b62516161306265685958524b422b7941773872537a6a4a476f3758523061467a414b4e70346c6f436e69484e564838373244504e4a77364b30336e544d69724b37725a615566485356754d477544473348366e4d78336c48436e6b517478764551474771754132676c416434424f427943414976483541566671655173534137776a4459702f494c6c66614e64307469467478344d6235566f6952513249387379384548547670307736667861316973613874636f484855614b32353857486474673d3d222c227369676e6174757265223a224d494147435371475349623344514548417143414d494143415145784454414c42676c67686b67425a514d45416745776741594a4b6f5a496876634e415163424141436767444343412b517767674f4c6f414d434151494343466e596f627971394f504e4d416f4743437147534d343942414d434d486f784c6a417342674e5642414d4d4a5546776347786c4945467763477870593246306157397549456c756447566e636d46306157397549454e4249433067527a4d784a6a416b42674e564241734d485546776347786c49454e6c636e52705a6d6c6a59585270623234675158563061473979615852354d524d77455159445651514b44417042634842735a53424a626d4d754d517377435159445651514745774a56557a4165467730794d5441304d6a41784f544d334d444261467730794e6a41304d546b784f544d324e546c614d4749784b44416d42674e5642414d4d4832566a5979317a62584174596e4a76613256794c584e705a32356656554d304c564e42546b5243543167784644415342674e564241734d43326c505579425465584e305a57317a4d524d77455159445651514b44417042634842735a53424a626d4d754d517377435159445651514745774a56557a425a4d424d4742797147534d34394167454743437147534d34394177454841304941424949772f6176446e50646549437851325a74464575593334716b423357797a344c484e53314a6e6d506a505472336f4769576f7768354d4d39334f6a697157777661766f5a4d445263546f656b516d7a7055624570576a676749524d4949434454414d42674e5648524d4241663845416a41414d42384741315564497751594d42614146435079536352506b2b54764a2b62453969687350364b372f53354c4d45554743437347415155464277454242446b774e7a4131426767724267454642516377415959706148523063446f764c32396a633341755958427762475575593239744c32396a633341774e433168634842735a5746705932457a4d4449776767456442674e5648534145676745554d4949424544434341517747435371475349623359325146415443422f6a4342777759494b77594242515548416749776762594d67624e535a5778705957356a5a5342766269423061476c7a49474e6c636e52705a6d6c6a5958526c49474a35494746756553427759584a306553426863334e316257567a4947466a593256776447467559325567623259676447686c4948526f5a5734675958427762476c6a59574a735a53427a644746755a4746795a4342305a584a7463794268626d5167593239755a476c3061573975637942765a6942316332557349474e6c636e52705a6d6c6a5958526c4948427662476c6a65534268626d51675932567964476c6d61574e6864476c7662694277636d466a64476c6a5a53427a644746305a57316c626e527a4c6a4132426767724267454642516343415259716148523063446f764c33643364793568634842735a53356a623230765932567964476c6d61574e68644756686458526f62334a7064486b764d44514741315564487751744d4373774b61416e6f43574749326830644841364c79396a636d77755958427762475575593239744c3246776347786c59576c6a59544d7559334a734d4230474131556444675157424251434a44414c6d753774526a4758704b5a614b5a3543635949635254414f42674e56485138424166384542414d43423441774477594a4b6f5a496876646a5a415964424149464144414b42676771686b6a4f5051514441674e4841444245416942306f624d6b32304a4a517733544a307851644d53416a5a6f6653413436686358424e69566d4d6c2b386f7749676154615155367631433170532b6659415463574b725778517039594961446551344b63363042354b3259457767674c754d49494364614144416745434167684a62532b2f4f706a616c7a414b42676771686b6a4f50515144416a426e4d527377475159445651514444424a42634842735a5342536232393049454e4249433067527a4d784a6a416b42674e564241734d485546776347786c49454e6c636e52705a6d6c6a59585270623234675158563061473979615852354d524d77455159445651514b44417042634842735a53424a626d4d754d517377435159445651514745774a56557a4165467730784e4441314d4459794d7a51324d7a4261467730794f5441314d4459794d7a51324d7a42614d486f784c6a417342674e5642414d4d4a5546776347786c4945467763477870593246306157397549456c756447566e636d46306157397549454e4249433067527a4d784a6a416b42674e564241734d485546776347786c49454e6c636e52705a6d6c6a59585270623234675158563061473979615852354d524d77455159445651514b44417042634842735a53424a626d4d754d517377435159445651514745774a56557a425a4d424d4742797147534d34394167454743437147534d34394177454841304941425041584559515a31325346315270654a594548647569416f752f656536354e34493338533550684d3162565a6c733172694c516c33594e496b353775676a396468664f694d743275325a7776736a6f4b59542f5645576a6766637767665177526759494b77594242515548415145454f6a41344d4459474343734741515546427a41426869706f644852774f69387662324e7a63433568634842735a53356a6232307662324e7a634441304c5746776347786c636d397664474e685a7a4d77485159445652304f4242594546435079536352506b2b54764a2b62453969687350364b372f53354c4d41384741315564457745422f7751464d414d4241663877487759445652306a42426777466f4155753744656f56677a694a716b69706e65767233727239724c4a4b73774e77594456523066424441774c6a41736f4371674b49596d6148523063446f764c324e7962433568634842735a53356a623230765958427762475679623239305932466e4d79356a636d777744675944565230504151482f42415144416745474d42414743697147534962335932514741673445416755414d416f4743437147534d343942414d43413263414d4751434d447250636f4e5246706d78687673317731624b59722f30462b335a4433564e6f6f362b385a7942586b4b33696669593935745a6e356a56515132506e656e432f6749774d693356524347776f7756336246337a4f4475515a2f305866437768625a5a50786e4a7067684a76565068366652755a7935734a6953466842706b50435a4964414141786767474a4d4949426851494241544342686a42364d5334774c4159445651514444435642634842735a5342426348427361574e6864476c766269424a626e526c5a334a6864476c7662694244515341744945637a4d5359774a4159445651514c44423142634842735a5342445a584a3061575a7059324630615739754945463164476876636d6c30655445544d424547413155454367774b51584277624755675357356a4c6a454c4d416b474131554542684d4356564d4343466e596f627971394f504e4d417347435743475341466c41775143416143426b7a415942676b71686b69473977304243514d784377594a4b6f5a496876634e415163424d42774743537147534962334451454a42544550467730794e4445794d5449784e6a51774d5452614d43674743537147534962334451454a4e4445624d426b774377594a59495a4941575544424149426f516f4743437147534d343942414d434d43384743537147534962334451454a4244456942434335615768366c647944637435626844536b62345835494a612b576f746d6d74344a624c74386949754a6b6a414b42676771686b6a4f50515144416752494d45594349514437637561364c6430697a6148716d5371713747303433476770363467484d6b514e523577757a32736137674968414e44643730585a6639432f412b58774e716a75672b76684c39534c4c4966465159746f6745377842534c774141414141414141222c22686561646572223a7b227075626c69634b657948617368223a225542347255754d6b7044627054564b7448636a6452525a496f643465766562754d4f696b7a4156556441593d222c22657068656d6572616c5075626c69634b6579223a224d466b77457759484b6f5a497a6a3043415159494b6f5a497a6a3044415163445167414557556a70324f663878427449432f354335535349544e443554736f75564c423831464547383847504b7243394e394d753365534e72586c32636564757533552f504f53652f616f75384477556a674e6670584d7831673d3d222c227472616e73616374696f6e4964223a2231363431326566383238303362633133356338333165396235663732376432366165623661616130363364633138353861313562323734386666346636333739227d2c2276657273696f6e223a2245435f7631227d2c227061796d656e744d6574686f64223a7b22646973706c61794e616d65223a224d6173746572436172642031343731222c226e6574776f726b223a224d617374657243617264222c2274797065223a226465626974227d2c227472616e73616374696f6e4964656e746966696572223a2231363431326566383238303362633133356338333165396235663732376432366165623661616130363364633138353861313562323734386666346636333739227d7d required: true responses: '201': description: Successful request. We processed the transaction. content: application/json: schema: required: &ref_214 - card - order - paymentId - processingTerminalId - transactionResult type: object properties: &ref_215 paymentId: maxLength: 10 minLength: 10 type: string description: Unique identifier that our gateway assigned to the transaction. example: M2MJOG6O2Y processingTerminalId: maxLength: 50 minLength: 4 type: string description: Unique identifier of the terminal that initiated the transaction. example: '1234001' operator: maxLength: 50 minLength: 0 type: string description: Operator who initiated the request. example: Jane order: type: object description: Object that contains information about the payment. allOf: &ref_194 - required: *ref_187 type: object description: Object that contains information about the payment. allOf: *ref_188 - type: object properties: breakdown: required: &ref_711 - subtotal type: object description: Object that contains information about the breakdown of the transaction. allOf: &ref_712 - type: object allOf: &ref_708 - required: *ref_189 type: object description: Object that contains information about the breakdown of the transaction. properties: *ref_190 - type: object properties: taxes: type: array description: List of taxes. items: required: *ref_124 type: object properties: *ref_125 - type: object properties: 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. example: 0 freightAmount: type: integer format: int64 description: | Amount for shipping in the currency's lowest denomination, for example, cents. example: 0 convenienceFee: required: *ref_172 type: object readOnly: true description: Object that contains information about the convenience fee for the transaction. properties: *ref_173 items: type: array description: Array of objects that contain information about each item that the customer purchased. items: description: Array of 'lineItem' objects. Each object contains information about the items in the transaction. type: object allOf: &ref_710 - required: *ref_191 type: object description: List of line items. properties: *ref_192 - type: object properties: taxes: type: array description: Array of objects that contain information about each tax that applies to the item. items: required: *ref_124 type: object properties: *ref_125 customer: type: object description: Object that contains the customer's contact details and address information. properties: *ref_193 card: required: &ref_256 - cardNumber - entryMethod - expiryDate - type type: object description: Object that contains the details of the payment card. properties: &ref_257 type: type: string description: Card brand of the card, for example, Visa. example: Visa entryMethod: type: string description: Method that the device used to capture the card details. enum: - icc - keyed - swiped - swipedFallback - contactlessIcc - contactlessMsr example: contactlessIcc cardholderName: maxLength: 50 minLength: 1 type: string description: Cardholder’s name. example: Sarah Hazel Hopper cardholderSignature: type: string description: Cardholder’s signature. example: a1b1c012345678a000b000c0012345d0e0f010g10061a031i001j071k0a1b0c1d0e1234567890120f1g0h1i0j1k0a1b0123451c012d0e1f0g1h0i1j123k1a1b1c1d1e1f1g123h1i1j1k1a1b1c1d1e1f1g123h123i1j123k12340a120a12345b012c0123012d0d1e0f1g0h1i123j123k10000 cardNumber: maxLength: 19 minLength: 12 type: string description: | Card number. In the response, our gateway shows only the first six digits and the last four digits of the card number, for example, 500165******0000. example: '4539858876047062' expiryDate: pattern: '[0-9]{4}' type: string description: Expiry date of the customer's card. The format is in **MMYY**. example: '0725' secureToken: required: *ref_138 type: object description: Object that contains information about the secure token. properties: *ref_139 securityChecks: type: object description: Object that contains information about card verification and security checks. properties: &ref_195 cvvResult: type: string 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. enum: - M - 'N' - P - U example: M avsResult: type: string 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. enum: - 'Y' - A - Z - 'N' - U - R - G - S - F - W - X example: 'Y' emvTags: type: array uniqueItems: true description: Array of emvTag objects. items: required: &ref_196 - hex - value type: object description: Object that contains information about the EMV tag. properties: &ref_197 hex: type: string description: Hex code of the EMV tag. example: 9F36 value: type: string description: Value of the EMV tag. example: '001234' example: - hex: 9F36 value: '001234' - hex: 5F2A value: '0840' balances: type: array description: Array of cardBalance objects. Our gateway returns this array only when the customer uses an Electronic Benefit Transfer (EBT) card. items: required: &ref_198 - amount - benefitCategory - currency type: object description: Object that contains information about the total funds available in the card. properties: &ref_199 benefitCategory: type: string description: | Indicates if the balance relates to an EBT Cash account or EBT SNAP account. - `cash` – EBT Cash - `foodStamp` – EBT SNAP enum: - cash - foodStamp example: cash amount: type: integer format: int64 description: Current balance of the account. This value is in the currency's lowest denomination, for example, cents. example: 50000 currency: type: string description: Currency of the transaction. The value for the currency follows the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard. enum: *ref_83 example: - benefitCategory: cash amount: 50000 currency: USD - benefitCategory: foodStamp amount: 10000 currency: USD refunds: type: array uniqueItems: true description: | Array of refundSummary objects. Each object contains information about refunds linked to the transaction. items: required: &ref_200 - amount - currency - dateTime - refundId - status - responseCode - responseMessage type: object description: Object that contains information about a refund. properties: &ref_201 refundId: maxLength: 10 minLength: 10 type: string description: Unique identifier of the refund. example: CD3HN88U9F dateTime: type: string format: date-time description: Date and time that the refund was processed. example: '2024-07-14T12:25:00Z' currency: type: string description: Currency of the transaction. The value for the currency follows the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard. enum: *ref_83 amount: type: integer format: int64 description: Amount of the refund. This value is in the currency’s lowest denomination, for example, cents. example: 4999 status: type: string description: Current status of the refund. enum: - ready - pending - declined - complete - referral - pickup - reversal - returned - admin - expired - accepted example: complete responseCode: type: string 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. enum: - A - D - E - P - R - C example: A responseMessage: maxLength: 48 minLength: 1 type: string description: Description of the response from the processor. example: Transaction refunded link: type: object readOnly: true description: Object that contains HATEOAS links for the resource. properties: *ref_4 required: *ref_5 example: *ref_6 supportedOperations: type: array items: &ref_202 type: string enum: - capture - refund - fullyReverse - partiallyReverse - incrementAuthorization - adjustTip - addSignature - setAsReady - setAsPending description: | Array of operations that you can perform on the transaction. - `capture` - Capture the payment. - `refund` - Refund the payment. - `fullyReverse` - Fully reverse the transaction. - `partiallyReverse` - Partially reverse the payment. - `incrementAuthorization` - Increase the amount of the authorization. - `adjustTip` - Adjust the tip post-payment. - `addSignature` - Add a signature to the payment. - `setAsReady` - Set the transaction’s status to `ready`. - `setAsPending` - Set the transaction’s status to `pending`. example: &ref_203 - capture - refund - fullyReverse - partiallyReverse - incrementAuthorization - adjustTip - addSignature - setAsReady - setAsPending transactionResult: required: &ref_204 - status - responseCode type: object properties: &ref_205 type: type: string description: Transaction type. enum: - sale - refund - preAuthorization - preAuthorizationCompletion ebtType: type: string description: Indicates the subtype of EBT in the transaction. enum: - cashPurchase - cashPurchaseWithCashback - foodStampPurchase - foodStampVoucherPurchase - foodStampReturn - foodStampVoucherReturn - cashBalanceInquiry - foodStampBalanceInquiry - cashWithdrawal status: type: string description: Current status of the transaction. enum: - ready - pending - declined - complete - referral - pickup - reversal - admin - expired - accepted approvalCode: maxLength: 48 minLength: 1 type: string description: Authorization code that the processor assigned to the transaction. authorizedAmount: type: integer format: int64 description: | Amount that the processor authorized for the transaction. This value is in the currency’s lowest denomination, for example, cents. **Notes:** - For partial authorizations, this amount is lower than the amount in the request. - If the value for **authorizedAmount** is negative, this indicates that the merchant sent funds to the customer. currency: type: string description: Currency of the transaction. The value for the currency follows the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard. enum: *ref_83 responseCode: type: string 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. enum: - A - D - E - P - R - C responseMessage: maxLength: 48 minLength: 1 type: string description: Response description from the processor. processorResponseCode: type: string description: Original response code that the processor sent. cardSchemeReferenceId: maxLength: 64 minLength: 1 type: string description: Identifier that the card brand assigns to the payment instruction. description: Object that contains information about the transaction response details. customFields: type: array description: | Array of customField objects. items: required: *ref_129 type: object properties: *ref_130 examples: createdPayment: summary: Payment description: Payment value: &ref_208 paymentId: M2MJOG6O2Y processingTerminalId: '1234001' operator: Jane order: orderId: OrderRef6543 dateTime: '2024-07-02T15:30:00Z' description: Large Pepperoni Pizza amount: 4999 currency: USD customer: firstName: Sarah lastName: Hopper billingAddress: address1: 1 Example Ave. address2: Example Address Line 2 address3: Example Address Line 3 city: Chicago state: Illinois country: US postalCode: '60056' shippingAddress: recipientName: Sarah Hopper address: address1: 1 Example Ave. address2: Example Address Line 2 address3: Example Address Line 3 city: Chicago state: Illinois country: US postalCode: '60056' card: type: MasterCard entryMethod: keyed cardNumber: 453985******7062 expiryDate: '1230' securityChecks: cvvResult: M avsResult: 'Y' supportedOperations: - capture - fullyReverse - partiallyReverse - incrementAuthorization - adjustTip - setAsPending transactionResult: type: sale status: ready approvalCode: OK3 authorizedAmount: 4999 currency: USD responseCode: A responseMessage: OK3 customFields: - name: yourCustomField value: abc123 applePaySaleResponse: summary: Apple Pay Payment value: &ref_954 paymentId: J9VULKIKFP processingTerminalId: '1234001' operator: Jane order: orderId: 1234567890W dateTime: '2024-07-02T15:30:00Z' description: Card Transaction (APPLE) amount: 4999 currency: USD card: type: MasterCard entryMethod: keyed cardNumber: 500165******0000 expiryDate: '0328' securityChecks: avsResult: U supportedOperations: - capture - fullyReverse - partiallyReverse - incrementAuthorization - adjustTip - setAsPending transactionResult: type: sale status: ready approvalCode: OK3 authorizedAmount: 4999 currency: USD responseCode: A responseMessage: APPROVAL processorResponseCode: '00' headers: location: description: URI reference to created resource. schema: *ref_24 examples: *ref_25 '400': description: Validation error content: application/problem+json: schema: type: object properties: *ref_9 required: *ref_10 examples: validationError: summary: Bad Request description: One or more validation errors occurred value: *ref_11 idempotentKeyMissing: summary: Idempotency key missing description: Idempotency key must be supplied value: *ref_26 idempotentKeyInUse: summary: Idempotency key in use description: Idempotency key in use value: *ref_29 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '406': description: Not acceptable content: *ref_19 '409': description: Conflict content: *ref_104 '415': description: Unsupported media type content: *ref_105 '500': description: An error has occured content: *ref_14 get: tags: - Payments summary: List payments description: | Use this method to return a [paginated](https://docs.payroc.com/api/pagination) list of payments. **Note:** If you want to view the details of a specific payment and you have its paymentId, use our [Retrieve Payment](https://docs.payroc.com/api/schema/card-payments/payments/retrieve) method. Use query parameters to filter the list of results that we return, for example, to search for payments for a customer, a tip mode, or a date range. Our gateway returns the following information about each payment in the list: - 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. For each transaction, we also return the paymentId and an optional secureTokenId, which you can use to perform follow-on actions. operationId: listPayments parameters: - name: processingTerminalId in: query description: Filter by terminal ID. schema: &ref_235 maxLength: 50 minLength: 4 type: string examples: &ref_236 example: value: '1234001' - name: orderId in: query description: Filter payments by order ID. schema: &ref_417 maxLength: 24 minLength: 1 type: string examples: &ref_418 example: value: OrderRef6543 - name: operator in: query description: Filter payments by operator. schema: &ref_419 maxLength: 50 minLength: 1 type: string examples: &ref_420 example: value: Jane - name: cardholderName in: query description: Filter payments by the cardholder’s name. schema: &ref_421 maxLength: 50 minLength: 1 type: string examples: &ref_422 example: value: Sarah%20Hazel%20Hopper - name: first6 in: query description: Filter payments by the first six digits of the card number that the customer used in the transaction. schema: &ref_423 pattern: '[0-9]{6}' type: string examples: &ref_424 example: value: '453985' - name: last4 in: query description: Filter payments by the last four digits of the card number that the customer used in the transaction. schema: &ref_425 pattern: '[0-9]{4}' type: string examples: &ref_426 example: value: '7062' - name: tender in: query description: Filter by tender type. schema: type: string enum: - ebt - creditDebit examples: example: value: ebt - name: tipMode in: query description: Filter payments by tip. schema: &ref_429 type: array items: type: string enum: - noTip - prompted - adjusted examples: &ref_430 example: value: - noTip - prompted - name: type in: query description: Filter payments by transaction type. schema: &ref_431 type: array items: type: string enum: - sale - preAuthorization - preAuthorizationCompletion examples: &ref_432 example: value: - sale - preAuthorization - name: status in: query description: Filter payments by the status of the transaction. schema: &ref_433 type: array items: type: string enum: - ready - pending - declined - complete - referral - pickup - reversal - admin - expired - accepted examples: &ref_434 example: value: - accepted - ready - complete - name: dateFrom in: query description: Filter by payments that the processor processed after a specific date. The date format follows the ISO 8601 standard. schema: &ref_435 type: string format: date-time examples: &ref_436 example: value: '2024-07-01T15:30:00Z' - name: dateTo in: query description: Filter by payments that the processer processed before a specific date. The date format follows the ISO 8601 standard. schema: &ref_437 type: string format: date-time examples: &ref_438 example: value: '2024-07-03T15:30:00Z' - name: settlementState in: query description: Filter payments by the settlement status of the transaction. schema: &ref_439 type: string enum: - settled - unsettled examples: &ref_440 example: value: settled - name: settlementDate in: query description: Filter by payments that the processor settled on a specific date in the format **YYYY-MM-DD**. schema: &ref_441 type: string format: date examples: &ref_442 example: value: '2024-07-02' - name: paymentLinkId in: query description: Unique identifier that our gateway assigned to the payment link. schema: &ref_443 maxLength: 10 minLength: 10 type: string examples: &ref_444 example: value: JZURRJBUPS - name: before in: query description: | Return the previous page of results before the value that you specify. You can’t send the before parameter in the same request as the after parameter. schema: *ref_32 examples: *ref_33 - name: after in: query description: | Return the next page of results after the value that you specify. You can’t send the after parameter in the same request as the before parameter. schema: *ref_34 examples: *ref_35 - name: limit in: query description: Limit the maximum number of results that we return for each page. schema: *ref_36 examples: *ref_37 responses: '200': description: Successful request. Returns a list of payments. content: application/json: schema: required: &ref_713 - count - data - hasMore - limit type: object allOf: &ref_714 - type: object description: Contains the pagination properties that you use to navigate through a list of results. properties: *ref_38 - type: object properties: data: type: array description: Array of transactions. items: required: &ref_206 - card - order - paymentId - processingTerminalId - transactionResult type: object properties: &ref_207 paymentId: maxLength: 10 minLength: 10 type: string description: Unique identifier that our gateway assigned to the transaction. example: M2MJOG6O2Y processingTerminalId: maxLength: 50 minLength: 4 type: string description: Unique identifier of the terminal that initiated the transaction. example: '1234001' operator: maxLength: 50 minLength: 0 type: string description: Operator who initiated the request. example: Jane order: type: object description: Object that contains information about the payment. allOf: *ref_194 customer: type: object description: Object that contains the customer's contact details and address information. properties: *ref_193 card: required: &ref_231 - cardNumber - expiryDate - type type: object description: Object that contains the details of the payment card. properties: &ref_232 type: type: string description: Card brand that the card is linked to. For example, Visa. example: Visa entryMethod: type: string description: Method that the device used to capture the card details. enum: - icc - keyed - swiped - swipedFallback - contactlessIcc - contactlessMsr example: contactlessIcc cardholderName: maxLength: 50 minLength: 1 type: string description: Cardholder’s name. example: Sarah Hazel Hopper cardholderSignature: type: string description: Cardholder’s signature. example: a1b1c012345678a000b000c0012345d0e0f010g10061a031i001j071k0a1b0c1d0e1234567890120f1g0h1i0j1k0a1b0123451c012d0e1f0g1h0i1j123k1a1b1c1d1e1f1g123h1i1j1k1a1b1c1d1e1f1g123h123i1j123k12340a120a12345b012c0123012d0d1e0f1g0h1i123j123k10000 cardNumber: maxLength: 19 minLength: 12 type: string 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. example: 453985******7062 expiryDate: pattern: '[0-9]{4}' type: string description: Expiry date of the customer's card. The format is in **MMYY**. example: '0725' secureToken: required: *ref_138 type: object description: Object that contains information about the secure token. properties: *ref_139 securityChecks: type: object description: Object that contains information about card verification and security checks. properties: *ref_195 emvTags: type: array uniqueItems: true description: Array of emvTag objects. items: required: *ref_196 type: object description: Object that contains information about the EMV tag. properties: *ref_197 example: - hex: 9F36 value: '001234' - hex: 5F2A value: '0840' balances: type: array description: Array of cardBalance objects. Our gateway returns this array only when the customer uses an Electronic Benefit Transfer (EBT) card. items: required: *ref_198 type: object description: Object that contains information about the total funds available in the card. properties: *ref_199 example: - benefitCategory: cash amount: 50000 currency: USD - benefitCategory: foodStamp amount: 10000 currency: USD refunds: type: array uniqueItems: true description: | Array of refundSummary objects. Each object contains information about refunds linked to the transaction. items: required: *ref_200 type: object description: Object that contains information about a refund. properties: *ref_201 supportedOperations: type: array items: *ref_202 description: | Array of operations that you can perform on the transaction. - `capture` - Capture the payment. - `refund` - Refund the payment. - `fullyReverse` - Fully reverse the transaction. - `partiallyReverse` - Partially reverse the payment. - `incrementAuthorization` - Increase the amount of the authorization. - `adjustTip` - Adjust the tip post-payment. - `addSignature` - Add a signature to the payment. - `setAsReady` - Set the transaction’s status to `ready`. - `setAsPending` - Set the transaction’s status to `pending`. example: *ref_203 transactionResult: required: *ref_204 type: object properties: *ref_205 description: Object that contains information about the transaction response details. customFields: type: array description: | Array of customField objects. items: required: *ref_129 type: object properties: *ref_130 examples: paginatedResults: summary: Payment description: Payment value: &ref_951 limit: 2 count: 2 hasMore: true data: - paymentId: M2MJOG6O2Y processingTerminalId: '1234001' operator: Automatic Payment order: orderId: OrderRef6543 dateTime: '2024-07-02T15:30:00Z' description: Monthly Premium Club subscription amount: 4999 currency: USD card: type: Visa Credit cardholderName: Sarah Hopper cardNumber: 453985******7062 expiryDate: '1230' entryMethod: keyed secureToken: secureTokenId: MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa customerName: Sarah Hopper token: '296753123456' status: notValidated link: rel: self method: GET href: https://api.payroc.com/v1/processing-terminals/1234001/secure-tokens/MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa securityChecks: cvvResult: M avsResult: X supportedOperations: - fullyReverse - setAsPending transactionResult: type: sale status: ready approvalCode: OK3 authorizedAmount: 4999 currency: USD responseCode: A responseMessage: APPROVAL - paymentId: E29U8OU8Q4 processingTerminalId: '1234001' operator: Automatic Payment order: orderId: OrderRef7654 dateTime: '2024-07-02T15:30:00Z' description: Monthly Premium Club subscription amount: 4999 currency: USD card: type: Visa Debit cardholderName: Sarah Hopper cardNumber: 453985******7062 expiryDate: '1230' entryMethod: keyed secureToken: secureTokenId: MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa customerName: Sarah Hopper token: '296753123456' status: notValidated link: rel: self method: GET href: https://api.payroc.com/v1/processing-terminals/1234001/secure-tokens/MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa securityChecks: cvvResult: M avsResult: X supportedOperations: - fullyReverse - setAsPending transactionResult: type: sale status: ready approvalCode: '475318' authorizedAmount: 1000 currency: EUR responseCode: A responseMessage: APPROVAL customFields: - name: yourCustomField value: abc123 links: - rel: next method: get href: https://api.payroc.com/v1/payments?processingTerminalId=1234001&limit=2&after=E29U8OU8Q4 - rel: previous method: get href: https://api.payroc.com/v1/payments?processingTerminalId=1234001&limit=2&before=M2MJOG6O2Y noActivity: summary: No records found description: Valid request, but no records match the criteria. value: *ref_55 '400': description: Invalid request content: *ref_15 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '406': description: Not acceptable content: *ref_19 '500': description: An error has occured content: *ref_14 /payments/{paymentId}: get: tags: - Payments summary: Retrieve payment operationId: getPayment description: | 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. parameters: - name: paymentId in: path required: true description: Unique identifier of the payment that the merchant wants to retrieve. schema: &ref_209 maxLength: 10 minLength: 10 type: string examples: &ref_210 example: value: M2MJOG6O2Y responses: '200': description: Successful request. Returns the payment. content: application/json: schema: required: *ref_206 type: object properties: *ref_207 examples: createdPayment: summary: Payment description: Payment value: *ref_208 '400': description: Invalid request content: *ref_15 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '404': description: Resource not found content: *ref_18 '406': description: Not acceptable content: *ref_19 '500': description: An error has occured content: *ref_14 /payments/{paymentId}/adjust: post: tags: - Payments summary: Adjust payment operationId: adjustPayment description: | Use this method to adjust a payment in an open batch. To adjust 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. You can adjust the following details of the payment: - Sale amount and tip amount - Payment status - Cardholder shipping address and contact information - Cardholder signature data Our gateway returns information about the adjusted payment, including information about the payment card and the cardholder. parameters: - name: Idempotency-Key in: header required: true 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). schema: *ref_22 examples: *ref_23 - name: paymentId in: path required: true description: Unique identifier of the payment that the merchant wants to retrieve. schema: *ref_209 examples: *ref_210 requestBody: content: application/json: schema: required: &ref_729 - adjustments type: object description: Object that contains the transaction adjustment object. properties: &ref_730 operator: maxLength: 50 minLength: 0 type: string description: Operator who adjusted the payment. example: Jane adjustments: type: array description: "Array of polymorphic objects which contain information about adjustments to a payment. \n\nThe value of the type parameter determines which variant you should use:\n-\t`order` - Tip information.\n-\t`status` - Status of the transaction.\n-\t`customer` - Customer's contact information and shipping address.\n-\t`signature` - Customer's signature.\n" uniqueItems: true items: discriminator: propertyName: type mapping: order: '#/components/schemas/orderAdjustment' status: '#/components/schemas/statusAdjustment' customer: '#/components/schemas/customerAdjustment' signature: '#/components/schemas/signatureAdjustment' oneOf: - required: &ref_725 - type - amount type: object title: order description: Object that contains information about the adjustment to the transaction. Send this object if the merchant is adjusting the order details. properties: &ref_726 type: type: string description: Type of adjustment. enum: - order example: order amount: exclusiveMinimum: 0 type: integer format: int64 description: Total amount of the transaction. example: 4999 breakdown: type: object description: Object that contains information about the tip amount of a transaction. properties: &ref_724 tip: required: *ref_211 type: object description: Object that contains information about the tip. properties: *ref_212 - required: &ref_242 - type - toStatus type: object title: status description: Object that contains information about the adjustment to the transaction. Send this object if the merchant is adjusting the status of the transaction. properties: &ref_243 type: type: string description: Type of adjustment. enum: - status example: status toStatus: type: string description: Status that you want to change the transaction to. enum: - ready - pending example: ready - required: &ref_244 - type type: object title: customer description: Object that contains information about the adjustment to the transaction. Send this object if the merchant is adjusting the customer’s contact details. properties: &ref_245 type: type: string description: Type of adjustment. enum: - customer example: customer shippingAddress: description: Object that contains information about the customer and their shipping address. type: object properties: *ref_213 contactMethods: uniqueItems: true 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" type: array items: discriminator: *ref_2 oneOf: *ref_3 - required: &ref_727 - type - cardholderSignature type: object title: signature description: | Object that contains the signature for the transaction. **Note:** If the merchant previously added a signature to the transaction, they can’t adjust or delete the signature. properties: &ref_728 type: type: string description: Type of adjustment. enum: - signature example: signature cardholderSignature: type: string description: Cardholder’s signature. For more information about the format of the signature, see Special Fields and Parameters. example: a1b1c012345678a000b000c0012345d0e0f010g10061a031i001j071k0a1b0c1d0e1234567890120f1g0h1i0j1k0a1b0123451c012d0e1f0g1h0i1j123k1a1b1c1d1e1f1g123h1i1j1k1a1b1c1d1e1f1g123h123i1j123k12340a120a12345b012c0123012d0d1e0f1g0h1i123j123k10000 examples: adjustPaymentRequest: summary: Adjust Payment description: Adjust Payment value: &ref_955 adjustments: - type: customer shippingAddress: recipientName: Sarah Hopper address: address1: 1 Example Ave. address2: Example Address Line 2 address3: Example Address Line 3 city: Chicago state: Illinois country: US postalCode: '60056' - type: order amount: 3999 required: true responses: '200': description: Successful request. We adjusted the transaction. content: application/json: schema: required: *ref_214 type: object properties: *ref_215 examples: adjustPaymentResponse: summary: Adjust Payment description: Adjust Payment value: &ref_956 paymentId: M2MJOG6O2Y processingTerminalId: '1234001' order: orderId: OrderRef6543 dateTime: '2024-07-02T15:30:00Z' description: Example payment amount: 4999 currency: USD customer: firstName: Sarah lastName: Hopper billingAddress: address1: 1 Example Ave. address2: Example Address Line 2 address3: Example Address Line 3 city: Chicago state: Illinois country: US postalCode: '60056' shippingAddress: recipientName: Sarah Hopper address: address1: 1 Example Ave. address2: Example Address Line 2 address3: Example Address Line 3 city: Chicago state: Illinois country: US postalCode: '60056' card: type: MasterCard entryMethod: keyed cardNumber: 453985******7062 expiryDate: '1230' securityChecks: cvvResult: M avsResult: 'Y' supportedOperations: - capture - fullyReverse - partiallyReverse - incrementAuthorization - adjustTip - setAsPending transactionResult: type: sale status: ready approvalCode: OK6 authorizedAmount: 4999 currency: USD responseCode: A responseMessage: OK6 customFields: - name: yourCustomField value: abc123 '400': description: Validation error content: application/problem+json: schema: type: object properties: *ref_9 required: *ref_10 examples: validationError: summary: Bad Request description: One or more validation errors occurred value: *ref_11 idempotentKeyMissing: summary: Idempotency key missing description: Idempotency key must be supplied value: *ref_26 idempotentKeyInUse: summary: Idempotency key in use description: Idempotency key in use value: *ref_29 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '404': description: Resource not found content: *ref_18 '406': description: Not acceptable content: *ref_19 '409': description: Conflict content: *ref_104 '415': description: Unsupported media type content: *ref_105 '500': description: An error has occured content: *ref_14 /payments/{paymentId}/capture: post: tags: - Payments summary: Capture payment operationId: capturePayment description: "Use this method to capture a pre-authorization. \n\nTo capture a pre-authorization, you need its paymentId. Our gateway returned the paymentId in the response of the [Create Payment](https://docs.payroc.com/api/schema/card-payments/payments/create) method.\n\n**Note:** If you don't have the paymentId, use our [List Payments](https://docs.payroc.com/api/schema/card-payments/payments/list) method to search for the payment.\n\nDepending on the amount you want to capture, complete the following:\n-\t**Capture the full amount of the pre-authorization** - Don't send a value for the amount parameter in your request.\n-\t**Capture less than the amount of the pre-authorization** - Send a value for the amount parameter in your request. \n-\t**Capture more than the amount of the pre-authorization** - Adjust the pre-authorization before you capture it. For more information about adjusting a pre-authorization, go to [Adjust Payment](https://docs.payroc.com/api/schema/card-payments/payments/adjust).\n\nIf your request is successful, our gateway takes the amount from the payment card. \n\n**Note:** For more information about pre-authorizations and captures, go to [Run a pre-authorization](https://docs.payroc.com/guides/integrate/run-a-pre-authorization).\n" parameters: - name: Idempotency-Key in: header required: true 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). schema: *ref_22 examples: *ref_23 - name: paymentId in: path required: true description: Unique identifier of the payment that the merchant wants to retrieve. schema: *ref_209 examples: *ref_210 requestBody: content: application/json: schema: description: Object that contains the details of the payment that the merchant wants to capture. type: object properties: &ref_731 processingTerminalId: maxLength: 50 minLength: 4 type: string description: Unique identifier that our gateway assigned to the terminal. operator: maxLength: 50 minLength: 0 type: string description: Operator who captured the payment. example: Jane amount: type: integer format: int64 description: | Amount that the merchant wants to capture. The value is in the currency's lowest denomination, for example, cents. **Note:** If the merchant does not send an amount, we capture the total amount of the transaction. example: 4999 breakdown: required: *ref_216 type: object description: Object that contains information about the breakdown of the transaction. allOf: *ref_217 examples: paymentCapture: summary: Payment capture description: Capture a payment with itemized breakdown value: &ref_957 processingTerminalId: '1234001' operator: Jane amount: 4999 breakdown: dutyAmount: 499 freightAmount: 500 subtotal: 4999 items: - unitPrice: 4000 quantity: 1 responses: '200': description: Successful request. We captured the payment. content: application/json: schema: required: *ref_214 type: object properties: *ref_215 examples: payment: summary: Payment description: Payment value: *ref_208 '400': description: Validation error content: application/problem+json: schema: type: object properties: *ref_9 required: *ref_10 examples: validationError: summary: Bad Request description: One or more validation errors occurred value: *ref_11 idempotentKeyMissing: summary: Idempotency key missing description: Idempotency key must be supplied value: *ref_26 idempotentKeyInUse: summary: Idempotency key in use description: Idempotency key in use value: *ref_29 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '404': description: Resource not found content: *ref_18 '406': description: Not acceptable content: *ref_19 '409': description: Conflict content: *ref_104 '415': description: Unsupported media type content: *ref_105 '500': description: An error has occured content: *ref_14 /payments/{paymentId}/reverse: post: tags: - Payments summary: Reverse payment operationId: reversePayment description: | Use this method to cancel or to partially cancel a payment in an open batch. This is also known as voiding a payment. To cancel 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. If your request is successful, our gateway removes the payment from the merchant's open batch and no funds are taken from the cardholder's account. parameters: - name: Idempotency-Key in: header required: true 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). schema: *ref_22 examples: *ref_23 - name: paymentId in: path required: true description: Unique identifier of the payment that the merchant wants to retrieve. schema: *ref_209 examples: *ref_210 requestBody: content: application/json: schema: type: object properties: &ref_732 operator: maxLength: 50 minLength: 0 type: string description: Operator who reversed the payment. amount: type: integer format: int64 description: | Amount of the payment that the merchant wants to reverse. The value is in the currency’s lowest denomination, for example, cents. **Note:** If the merchant doesn’t send an amount, we reverse the total amount of the transaction. examples: reversalPayment: summary: Reversal Payment description: Reversal Payment value: &ref_958 amount: 4999 responses: '200': description: Successful request. We reversed the payment. content: application/json: schema: required: *ref_214 type: object properties: *ref_215 examples: reversalPayment: summary: Reversal Payment description: Reversal Payment value: &ref_959 paymentId: M2MJOG6O2Y processingTerminalId: '1234001' order: orderId: OrderRef6543 dateTime: '2024-07-02T15:30:00Z' description: Large Pepperoni Pizza amount: 4999 currency: USD customer: firstName: Sarah lastName: Hopper billingAddress: address1: 1 Example Ave. address2: Example Address Line 2 address3: Example Address Line 3 city: Chicago state: Illinois country: US postalCode: '60056' shippingAddress: recipientName: Sarah Hopper address: address1: 1 Example Ave. address2: Example Address Line 2 address3: Example Address Line 3 city: Chicago state: Illinois country: IT postalCode: '60056' card: type: MasterCard entryMethod: keyed cardNumber: 453985******7062 expiryDate: '1230' securityChecks: cvvResult: M avsResult: 'Y' supportedOperations: - capture - fullyReverse - partiallyReverse - incrementAuthorization - adjustTip - setAsPending transactionResult: type: sale status: reversal approvalCode: OK2 authorizedAmount: 100 currency: USD responseCode: A responseMessage: OK2 customFields: - name: yourCustomField value: abc123 '400': description: Validation error content: application/problem+json: schema: type: object properties: *ref_9 required: *ref_10 examples: validationError: summary: Bad Request description: One or more validation errors occurred value: *ref_11 idempotentKeyMissing: summary: Idempotency key missing description: Idempotency key must be supplied value: *ref_26 idempotentKeyInUse: summary: Idempotency key in use description: Idempotency key in use value: *ref_29 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '404': description: Resource not found content: *ref_18 '406': description: Not acceptable content: *ref_19 '409': description: Conflict content: *ref_104 '415': description: Unsupported media type content: *ref_105 '500': description: An error has occured content: *ref_14 /payments/{paymentId}/refund: post: tags: - Payments summary: Create referenced refund operationId: refundPayment description: | Use this method to refund a payment that is in a closed batch. To refund 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. If your refund is successful, our gateway returns the payment amount to the cardholder's account. **Things to consider** - If the merchant refunds a payment that is in an open batch, our gateway reverses the payment. - Some merchants can run unreferenced refunds, which means that they don't need a paymentId to return an amount to a customer. For more information about how to run an unreferenced refund, go to [Create Refund](https://docs.payroc.com/api/schema/card-payments/refunds/create-unreferenced-refund). parameters: - name: Idempotency-Key in: header required: true 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). schema: *ref_22 examples: *ref_23 - name: paymentId in: path required: true description: Unique identifier of the payment that the merchant wants to retrieve. schema: *ref_209 examples: *ref_210 requestBody: content: application/json: schema: description: Object that contains the details of the payment that the merchant wants to refund. required: &ref_733 - amount - description type: object properties: &ref_734 operator: maxLength: 50 minLength: 0 type: string description: Operator who refunded the payment. example: Jane amount: type: integer format: int64 description: Amount of the payment that the merchant wants to refund. The value is in the currency’s lowest denomination, for example, cents. example: 4999 description: maxLength: 100 minLength: 1 type: string description: Reason for the refund. example: Customer requested a refund due to a wrong order. examples: refundPaymentRequest: summary: Refund Payment description: Refund Payment value: &ref_960 amount: 4999 description: Refund for order OrderRef6543 required: true responses: '200': description: Successful request. We refunded the payment. content: application/json: schema: required: *ref_214 type: object properties: *ref_215 examples: refundPayment: summary: Refund Payment description: Refund Payment value: &ref_961 paymentId: M2MJOG6O2Y processingTerminalId: '1234001' operator: Jane order: orderId: OrderRef6543 dateTime: '2024-07-02T15:30:00Z' description: Large Pepperoni Pizza amount: 4999 currency: USD customer: firstName: Sarah lastName: Hopper billingAddress: address1: 1 Example Ave. address2: Example Address Line 2 address3: Example Address Line 3 city: Chicago state: Illinois country: US postalCode: '60056' shippingAddress: recipientName: Sarah Hopper address: address1: 1 Example Ave. address2: Example Address Line 2 address3: Example Address Line 3 city: Chicago state: Illinois country: US postalCode: '60056' card: type: MasterCard entryMethod: keyed cardNumber: 453985******7062 expiryDate: '1230' securityChecks: cvvResult: M avsResult: 'Y' refunds: - refundId: CD3HN88U9F dateTime: '2024-07-02T15:30:00Z' amount: -4999 currency: USD status: ready responseCode: A responseMessage: Transaction refunded link: rel: self method: GET href: https://api.payroc.com/v1/refunds/BI77XQFQ05 supportedOperations: - refund transactionResult: type: sale status: complete approvalCode: OK3 authorizedAmount: 4999 currency: USD responseCode: A responseMessage: OK13 customFields: - name: yourCustomField value: acb123 '400': description: Validation error content: application/problem+json: schema: type: object properties: *ref_9 required: *ref_10 examples: validationError: summary: Bad Request description: One or more validation errors occurred value: *ref_11 idempotentKeyMissing: summary: Idempotency key missing description: Idempotency key must be supplied value: *ref_26 idempotentKeyInUse: summary: Idempotency key in use description: Idempotency key in use value: *ref_29 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '404': description: Resource not found content: *ref_18 '406': description: Not acceptable content: *ref_19 '409': description: Conflict content: *ref_104 '415': description: Unsupported media type content: *ref_105 '500': description: An error has occured content: *ref_14 /devices/{serialNumber}/payment-instructions: post: tags: - Payment instructions summary: Submit payment instruction operationId: sendPaymentInstruction description: | 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. parameters: - name: serialNumber description: Serial number of the merchant’s payment device. in: path required: true schema: &ref_445 maxLength: 64 minLength: 1 type: string examples: &ref_446 example: value: '1850010868' - name: Idempotency-Key in: header required: true 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). schema: *ref_22 examples: *ref_23 requestBody: required: true content: application/json: schema: required: &ref_738 - order - processingTerminalId type: object description: Object that contains the instructions for initiating a payment on a physical device. properties: &ref_739 operator: maxLength: 50 minLength: 0 type: string description: Operator who initiated the request. example: Jane processingTerminalId: maxLength: 50 minLength: 4 type: string description: Unique identifier that we assigned to the terminal. example: '1234001' order: required: &ref_736 - amount - currency - orderId type: object description: Object that contains information about the payment. allOf: &ref_737 - required: *ref_218 type: object description: Object that contains details about the transaction. properties: *ref_219 - type: object properties: breakdown: type: object allOf: &ref_735 - required: *ref_189 type: object description: Object that contains information about the breakdown of the transaction. properties: *ref_190 - type: object properties: taxes: type: array description: List of taxes. items: type: object required: *ref_170 properties: *ref_171 customer: type: object description: Object that contains the customer's contact details and address information. properties: *ref_176 ipAddress: required: *ref_177 type: object writeOnly: true description: Object that contains the IP address of the device that sent the request. properties: *ref_178 credentialOnFile: type: object description: Object that contains information about saving the customer’s payment details. properties: *ref_220 customizationOptions: type: object description: Object that contains available options to customize certain aspects of an instruction. properties: &ref_246 ebtDetails: type: object required: *ref_221 description: Object that contains information about the Electronic Benefit Transfer (EBT) transaction. properties: *ref_222 entryMethod: type: string 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. enum: - deviceRead - manualEntry - deviceReadOrManualEntry default: deviceRead example: deviceRead 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. example: true 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**. example: false examples: paymentInstructionRequest: summary: Payment Instruction description: Submit an instruction for initiating a payment on a physical device. value: &ref_962 operator: Jane processingTerminalId: '1234001' order: orderId: OrderRef6543 currency: USD amount: 4999 customizationOptions: entryMethod: deviceRead autoCapture: true responses: '202': description: Successful request. We accepted the payment instruction. content: application/json: schema: required: &ref_223 - paymentInstructionId - status type: object allOf: &ref_224 - type: object description: Object that contains information about the status of the instruction properties: &ref_247 status: type: string 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. enum: - canceled - completed - failure - inProgress example: completed 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: type: object readOnly: true description: Object that contains HATEOAS links for the resource. properties: *ref_4 required: *ref_5 example: *ref_6 - type: object properties: paymentInstructionId: maxLength: 36 minLength: 1 type: string description: Unique identifier that we assigned to the payment instruction. example: a37439165d134678a9100ebba3b29597 examples: paymentInstruction: summary: Payment instruction description: Object that contains information about the progress of the payment instruction. value: &ref_963 paymentInstructionId: a37439165d134678a9100ebba3b29597 status: inProgress link: rel: self method: GET href: https://api.payroc.com/v1/payment-instructions/a37439165d134678a9100ebba3b29597 '400': description: Validation error content: application/problem+json: schema: type: object properties: *ref_9 required: *ref_10 examples: validationError: summary: Bad Request description: One or more validation errors occurred value: *ref_11 idempotentKeyMissing: summary: Idempotency key missing description: Idempotency key must be supplied value: *ref_26 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '404': description: Resource not found content: *ref_18 '406': description: Not acceptable content: *ref_19 '409': description: Conflict content: *ref_104 '415': description: Unsupported media type content: *ref_105 '500': description: An error has occured content: *ref_14 /payment-instructions/{paymentInstructionId}: get: tags: - Payment instructions summary: Retrieve payment instruction operationId: getPaymentInstruction description: | 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. parameters: - name: paymentInstructionId description: Unique identifier that we assigned to the payment instruction. in: path required: true schema: &ref_225 maxLength: 36 minLength: 1 type: string examples: &ref_226 example: value: e743a9165d134678a9100ebba3b29597 responses: '200': description: Successful request. Returns the current status of the requested payment instruction. content: application/json: schema: required: *ref_223 type: object allOf: *ref_224 examples: paymentInstruction: summary: Payment instruction description: Object that contains information about the progress of the payment instruction. value: &ref_964 paymentInstructionId: a37439165d134678a9100ebba3b29597 status: completed link: rel: payment method: GET href: https://api.payroc.com/v1/payments/M2MJOG6O2Y '400': description: Invalid request content: *ref_15 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '404': description: Resource not found content: *ref_18 '406': description: Not acceptable content: *ref_19 '500': description: An error has occured content: *ref_14 delete: tags: - Payment instructions summary: Cancel payment instruction operationId: deletePaymentInstruction description: | 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. parameters: - name: paymentInstructionId description: Unique identifier that we assigned to the payment instruction. in: path required: true schema: *ref_225 examples: *ref_226 responses: '204': description: Successful request. We canceled the payment instruction. '400': description: Invalid request content: *ref_15 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '404': description: Resource not found content: *ref_18 '406': description: Not acceptable content: *ref_19 '409': description: Conflict content: application/problem+json: schema: type: object properties: *ref_27 required: *ref_28 examples: paymentInstructionCompleted: summary: Payment instruction already completed description: Payment instruction already completed value: &ref_965 type: https://docs.payroc.com/api/errors#cannot-be-canceled title: Cannot be canceled status: 409 detail: You cannot cancel this resource in its current state errors: - parameter: paymentInstructionId message: Completed instruction cannot be canceled link: rel: payment method: GET href: https://api.payroc.com/v1/payments/M2MJOG6O2Y paymentInstructionFailed: summary: Payment instruction failed description: Payment instruction failed value: &ref_966 type: https://docs.payroc.com/api/errors#cannot-be-canceled title: Cannot be canceled status: 409 detail: You cannot cancel this resource in its current state errors: - parameter: paymentInstructionId message: Failed instruction cannot be canceled '500': description: An error has occured content: *ref_14 /refunds: post: tags: - Refunds summary: Create unreferenced refund operationId: unreferencedRefund description: | Use this method to create an unreferenced refund. An unreferenced refund is a refund that isn't linked to a payment. **Note:** If you have the paymentId of the payment you want to refund, use our [Refund Payment](https://docs.payroc.com/api/schema/card-payments/refunds/create-referenced-refund) method. If you use our Refund Payment method, our gateway sends the refund amount to the customer's original payment method and links the refund to the payment. In the request, you must provide the customer's payment details and the refund amount. In the response, our gateway returns information about the refund and a refundId, which you need for the following methods: - [Retrieve refund](https://docs.payroc.com/api/schema/card-payments/refunds/retrieve) - View the details of the refund. - [Adjust refund](https://docs.payroc.com/api/schema/card-payments/refunds/adjust) - Update the details of the refund. - [Reverse refund](https://docs.payroc.com/api/schema/card-payments/refunds/reverse-refund) - Cancel the refund if it's in an open batch. parameters: - name: Idempotency-Key in: header required: true 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). schema: *ref_22 examples: *ref_23 requestBody: content: application/json: schema: required: &ref_742 - channel - order - processingTerminalId - refundMethod type: object description: Refund a payment that is not linked to a previous transaction. Unreferenced refunds are available only on certain accounts. properties: &ref_743 channel: type: string description: Channel that the merchant used to request the refund. enum: - pos - moto example: pos processingTerminalId: maxLength: 50 minLength: 4 type: string description: Unique identifier that we assigned to the terminal. example: '1234001' operator: maxLength: 50 minLength: 0 type: string description: Operator who initiated the request. example: Jane order: required: &ref_229 - amount - currency - description - orderId type: object description: Object that contains information about the refund. allOf: &ref_230 - required: *ref_218 type: object description: Object that contains details about the transaction. properties: *ref_219 - type: object properties: orderId: maxLength: 24 minLength: 1 type: string description: A unique identifier assigned by the merchant. example: OrderRef6543 dateTime: type: string format: date-time readOnly: true description: Date and time that our gateway processed the refund. The value follows the [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) standard. example: '2024-07-02T15:30:00Z' description: maxLength: 256 minLength: 1 type: string description: Description of the transaction. example: Refund for order OrderRef6543 amount: type: integer format: int64 description: Amount of the refund. The value is in the currency's lowest denomination, for example, cents. example: 4999 currency: type: string description: Currency of the transaction. The value for the currency follows the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard. enum: *ref_83 dccOffer: required: *ref_227 type: object 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). properties: *ref_228 customer: type: object description: Object that contains the customer's contact details and address information. properties: *ref_176 ipAddress: required: *ref_177 type: object writeOnly: true description: Object that contains the IP address of the device that sent the request. properties: *ref_178 refundMethod: description: "Polymorphic object that contains information about the payment method that the merchant uses to refund the customer. \n\nThe value of the type parameter determines which variant you should use:\n-\t`card` - Payment card details\n-\t`secureToken` - Secure token details\n" type: object discriminator: propertyName: type mapping: card: '#/components/schemas/cardPayload' secureToken: '#/components/schemas/secureTokenPayload' oneOf: - required: *ref_167 type: object writeOnly: true title: card description: Object that contains information about the customer’s payment card. properties: *ref_168 - required: *ref_179 type: object writeOnly: true title: secureToken description: Object that contains information about the secure token that represents the customer’s payment details. properties: *ref_180 customFields: type: array description: | Array of customField objects. items: required: *ref_129 type: object properties: *ref_130 examples: refund: summary: Refund description: Refund value: &ref_968 processingTerminalId: '1234001' order: orderId: OrderRef6543 description: Refund for order OrderRef6543 amount: 4999 currency: USD channel: pos refundMethod: type: card cardDetails: entryMethod: keyed keyedData: dataFormat: plainText device: model: paxA920 serialNumber: '1850010868' expiryDate: '1230' cardNumber: '4539858876047062' customFields: - name: yourCustomField value: abc123 required: true responses: '201': description: Successful request. We processed the refund. content: application/json: schema: required: &ref_237 - card - order - processingTerminalId - refundId - transactionResult type: object description: Object that contains information about the retrieved refund. properties: &ref_238 refundId: maxLength: 10 minLength: 10 type: string description: Unique identifier that our gateway assigned to the refund. example: CD3HN88U9F processingTerminalId: maxLength: 50 minLength: 4 type: string description: Unique identifier that we assigned to the terminal. example: '1234001' operator: maxLength: 50 minLength: 0 type: string description: Operator who requested the refund. example: Jane order: required: *ref_229 type: object description: Object that contains information about the refund. allOf: *ref_230 customer: type: object description: Object that contains the customer's contact details and address information. properties: *ref_193 card: required: *ref_231 type: object description: Object that contains the details of the payment card. properties: *ref_232 payment: required: *ref_233 type: object description: Object that contains information about a payment. properties: *ref_234 supportedOperations: type: array items: *ref_202 description: | Array of operations that you can perform on the transaction. - `capture` - Capture the payment. - `refund` - Refund the payment. - `fullyReverse` - Fully reverse the transaction. - `partiallyReverse` - Partially reverse the payment. - `incrementAuthorization` - Increase the amount of the authorization. - `adjustTip` - Adjust the tip post-payment. - `addSignature` - Add a signature to the payment. - `setAsReady` - Set the transaction’s status to `ready`. - `setAsPending` - Set the transaction’s status to `pending`. example: *ref_203 transactionResult: required: *ref_204 type: object properties: *ref_205 description: Object that contains information about the transaction response details. customFields: type: array description: | Array of customField objects. items: required: *ref_129 type: object properties: *ref_130 examples: refund: summary: Refund description: Refund value: &ref_239 refundId: CD3HN88U9F processingTerminalId: '1234001' order: orderId: OrderRef6543 dateTime: '2024-07-02T15:30:00Z' description: Refund for order OrderRef6543 amount: 4999 currency: USD card: type: Visa Credit entryMethod: keyed cardNumber: 453985******7062 expiryDate: '1230' transactionResult: type: refund status: ready approvalCode: '000000' authorizedAmount: -4999 currency: USD responseCode: A responseMessage: OK5 customFields: - name: yourCustomField value: abc123 headers: location: description: URI reference to created resource. schema: *ref_24 examples: *ref_25 '400': description: Validation error content: application/problem+json: schema: type: object properties: *ref_9 required: *ref_10 examples: validationError: summary: Bad Request description: One or more validation errors occurred value: *ref_11 idempotentKeyMissing: summary: Idempotency key missing description: Idempotency key must be supplied value: *ref_26 idempotentKeyInUse: summary: Idempotency key in use description: Idempotency key in use value: *ref_29 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '406': description: Not acceptable content: *ref_19 '409': description: Conflict content: *ref_104 '415': description: Unsupported media type content: *ref_105 '500': description: An error has occured content: *ref_14 get: tags: - Refunds summary: List refunds description: | Use this method to return a [paginated](https://docs.payroc.com/api/pagination) list of refunds. **Note:** If you want to view the details of a specific refund and you have its refundId, use our [Retrieve Refund](https://docs.payroc.com/api/schema/card-payments/refunds/retrieve) method. Use query parameters to filter the list of results that we return, for example, to search for refunds for a customer, a tender type, or a date range. Our gateway returns the following information about each refund in the list: - Order details, including the refund amount and when we processed the refund. - Payment card details, including the masked card number, expiry date, and payment method. - Cardholder details, including their contact information and shipping address. For referenced refunds, our gateway also returns details about the payment that the refund is linked to. operationId: listRefunds parameters: - name: processingTerminalId in: query description: Filter by terminal ID. schema: *ref_235 examples: *ref_236 - name: orderId in: query description: Filter refunds by the unique identifier that the merchant assigned to the order. schema: &ref_447 maxLength: 24 minLength: 1 type: string examples: &ref_448 example: value: OrderRef6543 - name: operator in: query description: Filter refunds by the operator who initiated the request. schema: &ref_449 maxLength: 50 minLength: 1 type: string examples: &ref_450 example: value: Jane - name: cardholderName in: query description: Filter refunds by cardholder name. schema: &ref_451 maxLength: 50 minLength: 1 type: string examples: &ref_452 example: value: Sarah%20Hazel%20Hopper - name: first6 in: query description: Filter refunds by the first six digits of the card number. schema: &ref_453 pattern: '[0-9]{6}' type: string examples: &ref_454 example: value: '453985' - name: last4 in: query description: Filter refunds by the last four digits of the card number. schema: &ref_455 pattern: '[0-9]{4}' type: string examples: &ref_456 example: value: '7062' - name: tender in: query description: Filter by tender type. schema: &ref_427 type: string enum: - ebt - creditDebit examples: &ref_428 example: value: ebt - name: status in: query description: Filter refunds by the current status of the refund. schema: &ref_457 type: array items: type: string enum: - ready - pending - declined - complete - referral - pickup - reversal - admin - expired - accepted examples: &ref_458 example: value: - accepted - ready - complete - name: dateFrom in: query description: Filter by refunds processed after a specific date. The date format follows the ISO 8601 standard. schema: &ref_459 type: string format: date-time examples: &ref_460 example: value: '2024-07-01T15:30:00Z' - name: dateTo in: query description: Filter by refunds processed before a specific date. The date format follows the ISO 8601 standard. schema: &ref_461 type: string format: date-time examples: &ref_462 example: value: '2024-07-03T15:30:00Z' - name: settlementState in: query description: Status of the settlement. schema: &ref_463 type: string enum: - settled - unsettled examples: &ref_464 example: value: settled - name: settlementDate in: query description: Date the transaction was settled. schema: &ref_465 type: string format: date examples: &ref_466 example: value: '2024-07-02' - name: before in: query description: | Return the previous page of results before the value that you specify. You can’t send the before parameter in the same request as the after parameter. schema: *ref_32 examples: *ref_33 - name: after in: query description: | Return the next page of results after the value that you specify. You can’t send the after parameter in the same request as the before parameter. schema: *ref_34 examples: *ref_35 - name: limit in: query description: Limit the maximum number of results that we return for each page. schema: *ref_36 examples: *ref_37 responses: '200': description: Successful request. Returns a paginated list of refunds. content: application/json: schema: required: &ref_740 - count - data - hasMore - limit type: object description: Object that contains information about refund objects. allOf: &ref_741 - type: object description: Contains the pagination properties that you use to navigate through a list of results. properties: *ref_38 - type: object properties: data: type: array description: Array of refund objects. items: required: *ref_237 type: object description: Object that contains information about the retrieved refund. properties: *ref_238 examples: paginatedResults: summary: Paginated Refund description: Paginated Refund value: &ref_967 limit: 2 count: 2 hasMore: true data: - refundId: CD3HN88U9F processingTerminalId: '1234001' order: orderId: OrderRef6543 dateTime: '2024-07-02T15:30:00Z' description: Refund for order OrderRef6543 amount: 4999 currency: USD card: type: Visa Credit entryMethod: keyed cardNumber: 453985******7062 expiryDate: '1230' transactionResult: type: refund status: ready approvalCode: '000000' authorizedAmount: -4999 currency: USD responseCode: A responseMessage: APPROVAL - refundId: B6ZOFZNVOP processingTerminalId: '1234001' order: orderId: OrderRef7654 dateTime: '2024-07-02T15:30:00Z' description: Refund for order OrderRef7654 amount: 3999 currency: USD card: type: MasterCard entryMethod: keyed cardNumber: 500165******0000 expiryDate: '0328' transactionResult: type: refund status: reversal approvalCode: '000000' authorizedAmount: -3999 currency: USD responseCode: A responseMessage: APPROVAL customFields: - name: yourCustomField value: abc123 links: - rel: next method: get href: https://api.payroc.com/v1/refunds?processingTerminalId=1234001&limit=2&after=B6ZOFZNVOP - rel: previous method: get href: https://api.payroc.com/v1/refunds?processingTerminalId=1234001&limit=2&before=CD3HN88U9F noActivity: summary: No records found description: Valid request, but no records match the criteria. value: *ref_55 '400': description: Invalid request content: *ref_15 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '406': description: Not acceptable content: *ref_19 '500': description: An error has occured content: *ref_14 /refunds/{refundId}: get: tags: - Refunds summary: Retrieve refund operationId: getRefund description: | Use this method to retrieve information about a refund. To retrieve a refund, you need its refundId. Our gateway returned the refundId in the response of the [Refund Payment](https://docs.payroc.com/api/schema/card-payments/refunds/create-referenced-refund) method or the [Create Refund](https://docs.payroc.com/api/schema/card-payments/refunds/create-unreferenced-refund) method. **Note:** If you don't have the refundId, use our [List Refunds](https://docs.payroc.com/api/schema/card-payments/refunds/list) method to search for the refund. Our gateway returns the following information about the refund: - Order details, including the refund amount and when we processed the refund. - Payment card details, including the masked card number, expiry date, and payment method. - Cardholder details, including their contact information and shipping address. If the refund is a referenced refund, our gateway also returns details about the payment that the refund is linked to. parameters: - name: refundId description: Unique identifier that our gateway assigned to the refund. in: path required: true schema: &ref_240 maxLength: 10 minLength: 10 type: string examples: &ref_241 example: value: CD3HN88U9F responses: '200': description: Successful request. Returns the specific refund. content: application/json: schema: required: *ref_237 type: object description: Object that contains information about the retrieved refund. properties: *ref_238 examples: refundResponse: summary: Refund description: Refund value: *ref_239 '400': description: Invalid request content: *ref_15 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '404': description: Resource not found content: *ref_18 '406': description: Not acceptable content: *ref_19 '500': description: An error has occured content: *ref_14 /refunds/{refundId}/adjust: post: tags: - Refunds summary: Adjust refund operationId: adjustRefund description: | Use this method to adjust a refund in an open batch. To adjust a refund, you need its refundId. Our gateway returned the refundId in the response of the [Refund Payment](https://docs.payroc.com/api/schema/card-payments/refunds/create-referenced-refund) method or the [Create Refund](https://docs.payroc.com/api/schema/card-payments/refunds/create-unreferenced-refund) method. **Note:** If you don’t have the refundId, use our [List Refunds](https://docs.payroc.com/api/schema/card-payments/refunds/list) method to search for the refund. You can adjust the following details of the refund: - Customer details, including shipping address and contact information. - Status of the refund. Our gateway returns information about the adjusted refund, including: - Order details, including the refund amount and when we processed the refund. - Payment card details, including the masked card number, expiry date, and payment method. - Cardholder details, including their contact information and shipping address. If the refund is a referenced refund, our gateway also returns details about the payment that the refund is linked to. parameters: - name: Idempotency-Key in: header required: true 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). schema: *ref_22 examples: *ref_23 - name: refundId description: Unique identifier that our gateway assigned to the refund. in: path required: true schema: *ref_240 examples: *ref_241 requestBody: content: application/json: schema: required: &ref_744 - adjustments type: object description: Object that contains information about the adjustment to the refund. properties: &ref_745 operator: maxLength: 50 minLength: 0 type: string description: Operator who requested the adjustment to the refund. example: Jane adjustments: type: array description: "Array of polymorphic objects that contain information about adjustments to the refund. \n\nThe value of the type parameter determines which variant you should use: \n-\t`status` - Status of the transaction.\n-\t`customer` - Customer's contact information and shipping address.\n" uniqueItems: true items: discriminator: propertyName: type mapping: status: '#/components/schemas/statusAdjustment' customer: '#/components/schemas/customerAdjustment' oneOf: - required: *ref_242 type: object title: status description: Object that contains information about the adjustment to the transaction. Send this object if the merchant is adjusting the status of the transaction. properties: *ref_243 - required: *ref_244 type: object title: customer description: Object that contains information about the adjustment to the transaction. Send this object if the merchant is adjusting the customer’s contact details. properties: *ref_245 examples: refundRequest: summary: Adjust Refund description: Adjust Refund value: &ref_969 operator: Jane adjustments: - type: customer contactMethods: - type: mobile value: '8445558735' required: true responses: '200': description: Successful request. We updated the refund. content: application/json: schema: required: *ref_237 type: object description: Object that contains information about the retrieved refund. properties: *ref_238 examples: refundResponse: summary: Adjust Refund description: Adjust Refund value: &ref_970 refundId: CD3HN88U9F processingTerminalId: '1234001' operator: Jane order: orderId: OrderRef6543 dateTime: '2024-07-02T15:30:00Z' description: Refund for order OrderRef6543 amount: 4999 currency: USD customer: contactMethods: - type: mobile value: '8445558735' card: type: Visa Credit entryMethod: keyed cardNumber: 453985******7062 expiryDate: '1230' transactionResult: type: refund status: ready approvalCode: '000000' authorizedAmount: -4999 currency: USD responseCode: A responseMessage: OK13 customFields: - name: yourCustomField value: abc123 '400': description: Validation error content: application/problem+json: schema: type: object properties: *ref_9 required: *ref_10 examples: validationError: summary: Bad Request description: One or more validation errors occurred value: *ref_11 idempotentKeyMissing: summary: Idempotency key missing description: Idempotency key must be supplied value: *ref_26 idempotentKeyInUse: summary: Idempotency key in use description: Idempotency key in use value: *ref_29 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '404': description: Resource not found content: *ref_18 '406': description: Not acceptable content: *ref_19 '409': description: Conflict content: *ref_104 '415': description: Unsupported media type content: *ref_105 '500': description: An error has occured content: *ref_14 /refunds/{refundId}/reverse: post: tags: - Refunds summary: Reverse refund operationId: reverseRefund description: | Use this method to cancel a refund in an open batch. To cancel a refund, you need its refundId. Our gateway returned the refundId in the response of the [Refund Payment](https://docs.payroc.com/api/schema/card-payments/refunds/create-referenced-refund) or [Create Refund](https://docs.payroc.com/api/schema/card-payments/refunds/create-unreferenced-refund) method. **Note:** If you don’t have the refundId, use our [List Refunds](https://docs.payroc.com/api/schema/card-payments/refunds/list) method to search for the refund. If your request is successful, the gateway removes the refund from the merchant’s open batch and no funds are returned to the cardholder’s account. parameters: - name: Idempotency-Key in: header required: true 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). schema: *ref_22 examples: *ref_23 - name: refundId description: Unique identifier that our gateway assigned to the refund. in: path required: true schema: *ref_240 examples: *ref_241 responses: '200': description: Successful request. We voided the refund. content: application/json: schema: required: *ref_237 type: object description: Object that contains information about the retrieved refund. properties: *ref_238 examples: refundResponse: summary: Reverse Refund description: Reverse Refund value: &ref_971 refundId: CD3HN88U9F processingTerminalId: '1234001' order: orderId: OrderRef6543 dateTime: '2024-07-02T15:30:00Z' description: Refund for order OrderRef6543 amount: 4999 currency: USD card: type: Visa Credit entryMethod: keyed cardNumber: 453985******7062 expiryDate: '1230' transactionResult: type: refund status: reversal approvalCode: '000000' authorizedAmount: -4999 currency: USD responseCode: A responseMessage: APPROVAL customFields: - name: yourCustomField value: abc123 '400': description: Validation error content: application/problem+json: schema: type: object properties: *ref_9 required: *ref_10 examples: validationError: summary: Bad Request description: One or more validation errors occurred value: *ref_11 idempotentKeyMissing: summary: Idempotency key missing description: Idempotency key must be supplied value: *ref_26 idempotentKeyInUse: summary: Idempotency key in use description: Idempotency key in use value: *ref_29 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '404': description: Resource not found content: *ref_18 '406': description: Not acceptable content: *ref_19 '409': description: Conflict content: *ref_104 '415': description: Unsupported media type content: *ref_105 '500': description: An error has occured content: *ref_14 /devices/{serialNumber}/refund-instructions: post: tags: - Refund instructions summary: Submit refund instruction operationId: sendRefundInstruction description: | Use this method to submit an instruction request to initiate a refund on a payment device. In the request, include the refund amount and currency. If the request is successful, our gateway returns information about the refund instruction and a refundInstructionId, which you need for the following methods: - [Retrieve refund instruction](https://docs.payroc.com/api/schema/payroc-cloud/refund-instructions/retrieve) - View the details of the refund instruction. - [Cancel refund instruction](https://docs.payroc.com/api/schema/payroc-cloud/refund-instructions/delete) - Cancel the refund instruction. parameters: - name: serialNumber description: Serial number that identifies the merchant’s payment device. in: path required: true schema: maxLength: 64 minLength: 1 type: string examples: example: value: '1850010868' - name: Idempotency-Key in: header required: true 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). schema: *ref_22 examples: *ref_23 requestBody: content: application/json: schema: required: &ref_748 - order - processingTerminalId type: object description: Object that contains information about the instruction request to initiate a refund on a payment device. properties: &ref_749 operator: maxLength: 50 minLength: 0 type: string description: Operator who initiated the request. example: Jane processingTerminalId: maxLength: 50 minLength: 4 type: string description: Unique identifier that we assigned to the terminal. example: '1234001' order: required: &ref_746 - amount - currency - description - orderId type: object description: Object that contains information about the refund. allOf: &ref_747 - required: *ref_218 type: object description: Object that contains details about the transaction. properties: *ref_219 - type: object customer: type: object description: Object that contains the customer's contact details and address information. properties: *ref_176 ipAddress: required: *ref_177 type: object writeOnly: true description: Object that contains the IP address of the device that sent the request. properties: *ref_178 customizationOptions: type: object description: Object that contains available options to customize certain aspects of an instruction. properties: *ref_246 examples: refundInstructionRequest: summary: Refund instruction description: Submit an instruction for initiating a refund on a physical device. value: &ref_972 operator: Jane processingTerminalId: '1234001' order: orderId: OrderRef6543 currency: USD amount: 4999 description: Refund for order OrderRef6543 customizationOptions: entryMethod: manualEntry required: true responses: '202': description: Successful request. We accepted the refund instruction. content: application/json: schema: required: &ref_248 - refundInstructionId - status type: object allOf: &ref_249 - type: object description: Object that contains information about the status of the instruction properties: *ref_247 - type: object properties: refundInstructionId: maxLength: 36 minLength: 1 type: string description: Unique identifier that we assigned to the refund instruction. example: a37439165d134678a9100ebba3b29597 examples: refundInstruction: summary: Refund instruction description: Object that contains information about the progress of the refund instruction. value: &ref_973 refundInstructionId: a37439165d134678a9100ebba3b29597 status: inProgress link: rel: self method: GET href: https://api.payroc.com/v1/refund-instructions/a37439165d134678a9100ebba3b29597 '400': description: Validation error content: application/problem+json: schema: type: object properties: *ref_9 required: *ref_10 examples: validationError: summary: Bad Request description: One or more validation errors occurred value: *ref_11 idempotentKeyMissing: summary: Idempotency key missing description: Idempotency key must be supplied value: *ref_26 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '404': description: Resource not found content: *ref_18 '406': description: Not acceptable content: *ref_19 '409': description: Conflict content: *ref_104 '415': description: Unsupported media type content: *ref_105 '500': description: An error has occured content: *ref_14 /refund-instructions/{refundInstructionId}: get: tags: - Refund instructions summary: Retrieve refund instruction operationId: getRefundInstruction description: | Use this method to retrieve information about a refund instruction. To retrieve a refund instruction, you need its refundInstructionId. Our gateway returned the refundInstructionId in the response of the [Submit Refund Instruction](https://docs.payroc.com/api/schema/payroc-cloud/refund-instructions/submit) method. Our gateway returns the status of the refund instruction. If the payment device completed the refund instruction, the response also includes a link to the refund. parameters: - name: refundInstructionId description: Unique identifier that we assigned to the refund instruction. in: path required: true schema: &ref_250 maxLength: 36 minLength: 1 type: string examples: &ref_251 example: value: a37439165d134678a9100ebba3b29597 responses: '200': description: Successful request. Returns the current status of the requested refund instruction. content: application/json: schema: required: *ref_248 type: object allOf: *ref_249 examples: refundInstruction: summary: Refund instruction description: Object that contains information about the progress of the refund instruction. value: &ref_974 refundInstructionId: a37439165d134678a9100ebba3b29597 status: completed link: rel: refund method: GET href: https://api.payroc.com/v1/refunds/CD3HN88U9F '400': description: Invalid request content: *ref_15 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '404': description: Resource not found content: *ref_18 '406': description: Not acceptable content: *ref_19 '500': description: An error has occured content: *ref_14 delete: tags: - Refund instructions summary: Cancel refund instruction operationId: deleteRefundInstruction description: | Use this method to cancel a refund instruction. You can cancel a refund instruction only if its status is `inProgress`. To retrieve the status of a refund instruction, use our [Retrieve Refund Instruction](https://docs.payroc.com/api/schema/payroc-cloud/refund-instructions/retrieve) method. To cancel a refund instruction, you need its refundInstructionId. Our gateway returned the refundInstructionId in the response of the [Submit Refund Instruction](https://docs.payroc.com/api/schema/payroc-cloud/refund-instructions/submit) method. parameters: - name: refundInstructionId description: Unique identifier that we assigned to the refund instruction. in: path required: true schema: *ref_250 examples: *ref_251 responses: '204': description: Successful request. We canceled the refund instruction. '400': description: Invalid request content: *ref_15 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '404': description: Resource not found content: *ref_18 '406': description: Not acceptable content: *ref_19 '409': description: Conflict content: application/problem+json: schema: type: object properties: *ref_27 required: *ref_28 examples: refundInstructionCompleted: summary: Refund instruction already completed description: Refund instruction already completed value: &ref_975 type: https://docs.payroc.com/api/errors#cannot-be-canceled title: Cannot be canceled status: 409 detail: You cannot cancel this resource in its current state errors: - parameter: refundInstructionId message: Completed instruction cannot be canceled link: rel: refund method: GET href: https://api.payroc.com/v1/refunds/M2MJOG6O2Y refundInstructionFailed: summary: Refund instruction failed description: Refund instruction failed value: &ref_976 type: https://docs.payroc.com/api/errors#cannot-be-canceled title: Cannot be canceled status: 409 detail: You cannot cancel this resource in its current state errors: - parameter: refundInstructionId message: Failed instruction cannot be canceled '500': description: An error has occured content: *ref_14 /devices/{serialNumber}/signature-instructions: post: tags: - Signature instructions summary: Submit signature instruction operationId: sendSignatureInstruction description: | Use this method to submit an instruction to capture a customer's signature on a payment device. Our gateway returns information about the signature instruction and a signatureInstructionId, which you need for the following methods: - [Retrieve signature instruction](https://docs.payroc.com/api/schema/payroc-cloud/signature-instructions/retrieve) - View the details of the signature instruction. - [Cancel signature instruction](https://docs.payroc.com/api/schema/payroc-cloud/signature-instructions/delete) - Cancel the signature instruction. parameters: - name: serialNumber description: Serial number that identifies the merchant’s payment device. in: path required: true schema: &ref_467 maxLength: 64 minLength: 1 type: string examples: &ref_468 example: value: '1850010868' - name: Idempotency-Key in: header required: true 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). schema: *ref_22 examples: *ref_23 requestBody: required: true content: application/json: schema: required: &ref_750 - processingTerminalId type: object description: Object that contains the instructions for capturing a signature on a physical device. properties: &ref_751 processingTerminalId: maxLength: 50 minLength: 4 type: string description: Unique identifier that we assigned to the terminal. example: '1234001' examples: signatureInstructionRequest: summary: Signature Instruction description: Submit an instruction for capturing a signature on a physical device. value: &ref_977 processingTerminalId: '1234001' responses: '202': description: Successful request. We accepted the signature instruction. content: application/json: schema: required: &ref_252 - signatureInstructionId - status type: object allOf: &ref_253 - type: object description: Object that contains information about the status of the instruction properties: *ref_247 - type: object properties: signatureInstructionId: maxLength: 36 minLength: 1 type: string description: Unique identifier that our gateway assigned to the instruction. example: a37439165d134678a9100ebba3b29597 examples: signatureInstruction: summary: Signature instruction description: Object that contains information about the progress of the signature instruction. value: &ref_978 signatureInstructionId: a37439165d134678a9100ebba3b29597 status: inProgress link: rel: self method: GET href: https://api.payroc.com/v1/signature-instructions/a37439165d134678a9100ebba3b29597 '400': description: Validation error content: application/problem+json: schema: type: object properties: *ref_9 required: *ref_10 examples: validationError: summary: Bad Request description: One or more validation errors occurred value: *ref_11 idempotentKeyMissing: summary: Idempotency key missing description: Idempotency key must be supplied value: *ref_26 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '404': description: Resource not found content: *ref_18 '406': description: Not acceptable content: *ref_19 '409': description: Conflict content: *ref_104 '415': description: Unsupported media type content: *ref_105 '500': description: An error has occured content: *ref_14 /signature-instructions/{signatureInstructionId}: get: tags: - Signature instructions summary: Retrieve signature instruction operationId: getSignatureInstruction description: | Use this method to retrieve information about a signature instruction. To retrieve a signature instruction, you need its signatureInstructionId. Our gateway returned the signatureInstructionId in the response of the [Submit Signature Instruction](https://docs.payroc.com/api/schema/payroc-cloud/signature-instructions/submit) method. Our gateway returns the status of the instruction. If the payment device completed the instruction, the response also includes a link to retrieve the signature. parameters: - name: signatureInstructionId description: Unique identifier that our gateway assigned to the signature instruction. in: path required: true schema: &ref_254 maxLength: 36 minLength: 1 type: string examples: &ref_255 example: value: a37439165d134678a9100ebba3b29597 responses: '200': description: Successful request. Returns the signature instruction. content: application/json: schema: required: *ref_252 type: object allOf: *ref_253 examples: signatureInstruction: summary: Signature instruction description: Object that contains information about the progress of the signature instruction. value: &ref_979 signatureInstructionId: a37439165d134678a9100ebba3b29597 status: completed link: rel: signature method: GET href: https://api.payroc.com/v1/signatures/M2MJOG6O2Y '400': description: Invalid request content: *ref_15 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '404': description: Resource not found content: *ref_18 '406': description: Not acceptable content: *ref_19 '500': description: An error has occured content: *ref_14 delete: tags: - Signature instructions summary: Cancel signature instruction operationId: deleteSignatureInstruction description: | Use this method to cancel a signature instruction. To cancel a signature instruction, you need its signatureInstructionId. Our gateway returned the signatureInstructionId in the response of the [Submit signature instruction](https://docs.payroc.com/api/schema/payroc-cloud/signature-instructions/submit) method. parameters: - name: signatureInstructionId description: Unique identifier that our gateway assigned to the signature instruction. in: path required: true schema: *ref_254 examples: *ref_255 responses: '204': description: Successful request. We canceled the signature instruction. '400': description: Invalid request content: *ref_15 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '404': description: Resource not found content: *ref_18 '406': description: Not acceptable content: *ref_19 '409': description: Conflict content: application/problem+json: schema: type: object properties: *ref_27 required: *ref_28 examples: signatureInstructionCompleted: summary: Signature instruction already completed description: Signature instruction already completed value: &ref_980 type: https://docs.payroc.com/api/errors#cannot-be-canceled title: Cannot be canceled status: 409 detail: You cannot cancel this resource in its current state errors: - parameter: signatureInstructionId message: Completed instruction cannot be canceled link: rel: signature method: GET href: https://api.payroc.com/v1/signatures/M2MJOG6O2Y signatureInstructionFailed: summary: Signature instruction failed description: Signature instruction failed value: &ref_981 type: https://docs.payroc.com/api/errors#cannot-be-canceled title: Cannot be canceled status: 409 detail: You cannot cancel this resource in its current state errors: - parameter: signatureInstructionId message: Failed instruction cannot be canceled '500': description: An error has occured content: *ref_14 /signatures/{signatureId}: get: tags: - Signatures summary: Retrieve signature description: | Use this method to retrieve a signature that a payment device captured using Payroc Cloud. Our gateway returns the following information about the signature: - Image of the signature - Format of the image - Date that the device captured the image operationId: retrieveSignature parameters: - name: signatureId in: path description: Unique identifier that we assigned to the signature. required: true schema: &ref_469 type: string minLength: 10 maxLength: 10 examples: &ref_470 example: value: JDN4ILZB0T responses: '200': description: Successful request. Returns the signature. content: application/json: schema: type: object properties: signatureId: type: string description: Unique identifier that we assigned to the signature. example: JDN4ILZB0T processingTerminalId: type: string description: Unique identifier of the terminal that the signature is linked to. example: '1234001' createdOn: type: string format: date description: Date that the device captured the signature. The format of this value is **YYYY-MM-DD**. example: '2024-07-02' contentType: type: string description: MIME type that indicates the format of the image file. example: image/png signature: type: string description: Image data for the signature. Our gateway returns the signature as a Base64-encoded value. example: iVBORw0KGgoAAAANSUhEUgAAAoAAAAHgCAYAAAA10dzkAAAABHNCSVQICAgIfAhkiAAAAAlwSFlzAAALEgAACxIB0t1+/AAAADh0RVh0U29mdHdhcmUAbWF0cGxvdGxpYiB2ZXJzaW9uMy4xLjMsIGh0dHA6Ly9tYXRwbG90bGliLm9yZy+AADFEAAAgAElEQVR4nO3df5DkVZ3/8c+7s examples: signature: summary: Signature description: A signature response example. value: &ref_982 signatureId: JDN4ILZB0T processingTerminalId: '1024' createdOn: '2024-07-02' contentType: image/png signature: iVBORw0KGgoAAAANSUhEUgAAASwAAABkCAYAAAA8AQ3AAAAJT0lEQVR4Xu3dW4hN7x/H8UnOF5ScSaGcY4hyvJiSQ6RE3FDIkEuHNDdcKacc0pSQiCuUw4UL5YKcipGQclYkJKcccv7+/58ne35jzZ5t7b3XWns/a96v2s2etdfMYDyf/Xyf51nPqjDk9Pr1a7t06ZLt2bPH1qxZY7NmzbJBgwZZ69atrbKy0qqrq622ttbq6urs69evwS/P27Nnz2zYsGHBwwD+ryJ4wDffvn2z48eP29y5c12IVFRUZH20adPGzp07F/xy58ePH3bnzh07ceKEbd682RYvXmxjx461Tp06uYee65he0zk699OnTy6kFFYKLYVXu3btig6xBQsW2Pr164OHAZjHgaXwUTAoUKqqqmz//v32/v374Gn1dH7Xrl3/Cq3v37/bxo0bXZip16Tek3pR6k2pV6XeVT4UTsEQ0/d+/Phx8NSsrl69ar169XJhCKAxrwLr9u3bVlNTY3369LERI0bYli1bXAkVVsPQOn/+vA0ZMsRmzpxpT548CZ4aGfXKpk+fHjyc1cSJE+3AgQPBwwD+KPvAUiApmBRQCioFloKrUKdOnbK2bdtat27dXCkZN5Wbw4cPtyNHjgRf+svRo0dt1KhR9uvXr+BLAP4oy8BSaacST6WeSj6VV02NP4X1+/dv27dvn+thzZ8/37p06VL09wzrypUrrtRrqmRVKdm3b9/E/jyAr8ousA4ePOh6QBpEVw9Ig+rFunnzpo0fP9499FwUDhpfSsqKFSvcIxuVjbNnzw4eBhBQNoH1+fNnW7RokQ0dOtTNwkXh48ePbhBdvSr1rtTLakizh0lR70q9LPW2Gnr16pV17tzZHjx48NdxAI0l12JzUEApqBRYCq4oqHemMS99z6Zm+5IMLNE4lsazNK6VsXz5clu1alWDswA0JdkWm4VKQI0n6WMUNOOnmT/NAGomMJekA0s0Y6gSUDR5oMH/d+/eBc4CkE3yLfaPOErAe/fuufEvra3SGqt/KUVgaU1WZuxsypQpbs0WgHCSb7EWTwmoMmvMmDG2e/fu4EtNKkVgiX7u6dOnbfDgwX+VhwByS7zFRl0CZqxbt85mzJgRPJxTKQNLYaXQAhBeYi02jhIw4/Lly9ajRw97+fJl8KWcShlYKgcB5CeRFhtHCZihpQv9+/e3kydPBl/6p1IElgbY9XOLWa0PNFext9i4SsCMpUuXuke+dAmMdndImpYwlCIogTSIreXEWQJmqFel3pV6WfnS2iwt2EySFofqZxJYQGFiaTlxloAZGq/SuJXGrwpx9+5dGzhwYPBwrHT5jdZgEVhAYSJvObpGTxvZxVUCZmhGUDODhbp48aJNmDAheDg2+nfRBc4fPnwoSSkKpEGkgZVtk7w4aK2V1lwVs4ZJ5aQ27EuCxsu0dYy2kNEmfSNHjgyeAiCEyAIrqbASrRTXqvZiaPuaJUuWBA/HQpvyaXM+UdgWMkkAIKLASjKsJIoxII0lrV27Nng4ctruWLs0qGclCqt8VuMD+E/RLT/psJIoAkthlbkIOQ5v3751Zee4cePczGCuG2SEebRq1arRsYavAc1BUS2/FGElaqTFUjmosjAquqj50KFDtmzZMrdTRIcOHWzq1KnWsmVLO3bsmH358sXtLNq+ffu876TzL1H8ewA+KPh/eqnCSqJooBpwL2R1vGgjwBs3btiuXbts3rx51rNnT/fQcx3Tazrn6dOn1rt37/qvi2vAPYp/D8AHBf1PL2VYSRQNVEsatLQhDPWO9HfdsGGDTZs2zfWe1ItSb0q9qqZu46U1YrqnYUYcA+76cyW51TNQSnm3/FKHlWg8SDccvXDhQvCl0LRoVItHG8p1l2cFj46pV6bxqTC0w6j2ps+IesC9HH4XQJLyCqxyaSBv3ryxHTt2uF6OHnquY2Fk7vKsXpLusBzmLs+Frvfatm2brVy5sv5zlYOZ2cJilcvvAkhS6MAq1waiXpZ6W2Fn4XTegAEDrEWLFrZ69eqC7/IchsJKoSUKPu2GGsWAe7n+LoC4hQqstDWQw4cPJ7LKXeWgykJdT6lrK6O4XCltvwsgH/8MrDQ2EIWVQituKi818K6LwPUoxs+fP23r1q3uOs00/S6AfOQMrDSGlS4+7tixo/sYNy1p2L59u+tdFbNrxfXr1921iNqltKkZSaA5aDKwHj16lMp386TKQdF4mZYcFLofmEJOM5O6FZiWTwDNXZOBpXdzlSBpk1Q5WKwzZ8647Wg0oRDHhADgo6yBpXdzlSAaN0mTJMvBQimcFFIKK4UWgP80Ciw1mO7du7txk7RJshwshN4oVP6pDCxmzAtIq0aBtXDhQtdgmqI7Kt+6dcttRqcdP+fMmeMGlZPebrgQ5VoOaiBdJbh6tWl8owCi8ldgqQTp169f1nd37Zq5c+dON4isgFJQKbAUXAqwMLeGL6VyLAd1iU9NTY1bUKrxwrSV4EDU6gNLIaWwyjZu8vDhQ5s0aZJ76LmPyqkc1MXUmzZtcrc/0wXUz58/D54CIIv6wFIZqHKwoUyvSg1LH/W5r8qhHNQ1iXv37nU7kGormmK3eQaaGxdYGjfRQHvD6fM09KoyVAaqlC1lOajSWdcwTp482a5duxZ8GUAIFRo30WBvZmFi5mJijav43qvKKGU5ePbsWRs9erR76DmAwlVosLeqqqrg7Vp8UIpyUL0o9abUq1LvCkDxKnT5SBQb4pWrpGcHNS6l8SmNU2m8qtC9tAA0VqE9ohpuMpc2SZWDmunTjJ8mKDQDqJlAANFyPawXL14Ej6dGHOWgNuGrq6uz2tpaq66utsrKSjeorzVVYbdPBpC/Rivd00ZBcv/+/eDh0LKFk3ax0Ed9ruN6PYqdRAHklvrAUrkbtuQlnIDylvrAUrmbz37vhBNQvlIfWADSg8AC4A0CC4A3CCwA3iCwAHiDwALgDQILgDcILADeILAAeIPAAuANAguANwgsAN4gsAB4g8AC4A0CC4A3CCwA3iCwAHiDwALgDQILgDcILADeILAAeIPAAuANAguANwgsAN4gsAB4g8AC4A0CC4A3CCwA3iCwAHiDwALgDQILgDcILADeILAAeIPAAuANAguANwgsAN4gsAB4g8AC4A0CC4A3CCwA3iCwAHiDwALgDQILgDcILADeILAAeIPAAuANAguANwgsAN4gsAB4g8AC4A0CC4A3/gdbd1ZfSyjQ+QAAAABJRU5ErkJggg== '400': description: Invalid request content: *ref_15 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '404': description: Resource not found content: *ref_18 '406': description: Not acceptable content: *ref_19 '500': description: An error has occured content: *ref_14 /cards/verify: post: tags: - Cards summary: Verify card operationId: verifyCard description: | Use this method to verify a customer’s card details. In the request, send the customer’s card details. In the response, our gateway indicates if the card details are valid and if you should use them in follow-on actions. parameters: - name: Idempotency-Key in: header required: true 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). schema: *ref_22 examples: *ref_23 requestBody: content: application/json: schema: required: &ref_752 - card - processingTerminalId type: object properties: &ref_753 processingTerminalId: maxLength: 50 minLength: 4 type: string description: Unique identifier that we assigned to the terminal. example: '1234001' operator: maxLength: 50 minLength: 0 type: string description: Operator who requested to verify the card. example: Jane customer: type: object description: Object that contains the customer's contact details and address information. properties: *ref_176 card: type: object description: Polymorphic object that contains payment details. discriminator: propertyName: type mapping: card: '#/components/schemas/cardPayload' oneOf: - required: *ref_167 type: object writeOnly: true title: card description: Object that contains information about the customer’s payment card. properties: *ref_168 examples: cardVerificationRequest: summary: Card Verification description: Card Verification value: &ref_983 operator: Jane processingTerminalId: '1234001' card: type: card cardDetails: entryMethod: keyed cardholderName: Sarah Hazel Hopper cardholderSignature: a1b1c012345678a000b000c0012345d0e0f010g10061a031i001j071k0a1b0c1d0e1234567890120f1g0h1i0j1k0a1b0123451c012d0e1f0g1h0i1j123k1a1b1c1d1e1f1g123h1i1j1k1a1b1c1d1e1f1g123h123i1j123k12340a120a12345b012c0123012d0d1e0f1g0h1i123j123k10000 keyedData: dataFormat: plainText cardNumber: '4539858876047062' expiryDate: '1230' required: true responses: '200': description: Successful request. Returns the verification status of the card details. content: application/json: schema: required: &ref_754 - processingTerminalId - verified type: object properties: &ref_755 operator: maxLength: 50 minLength: 0 type: string description: Operator who requested to verify the card. example: Jane processingTerminalId: maxLength: 50 minLength: 4 type: string description: Unique identifier that we assigned to the terminal. example: '1234001' card: required: *ref_256 type: object description: Object that contains the details of the payment card. properties: *ref_257 verified: type: boolean description: | Indicates if the card details are valid: - `true` - Card details are valid. - `false` - Card details are not valid. example: true transactionResult: required: *ref_204 type: object properties: *ref_205 description: Object that contains information about the transaction response details. examples: cardVerificationResponse: summary: Card Verification description: Card Verification value: &ref_984 operator: Jane processingTerminalId: '1234001' card: type: Visa Credit entryMethod: keyed cardholderName: Sarah Hazel Hopper cardholderSignature: a1b1c012345678a000b000c0012345d0e0f010g10061a031i001j071k0a1b0c1d0e1234567890120f1g0h1i0j1k0a1b0123451c012d0e1f0g1h0i1j123k1a1b1c1d1e1f1g123h1i1j1k1a1b1c1d1e1f1g123h123i1j123k12340a120a12345b012c0123012d0d1e0f1g0h1i123j123k10000 cardNumber: 453985******7062 expiryDate: '1230' verified: true transactionResult: status: ready responseCode: A responseMessage: APPROVAL processorResponseCode: '00' '400': description: Validation error content: application/problem+json: schema: type: object properties: *ref_9 required: *ref_10 examples: validationError: summary: Bad Request description: One or more validation errors occurred value: *ref_11 idempotentKeyMissing: summary: Idempotency key missing description: Idempotency key must be supplied value: *ref_26 idempotentKeyInUse: summary: Idempotency key in use description: Idempotency key in use value: *ref_29 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '404': description: Resource not found content: *ref_18 '406': description: Not acceptable content: *ref_19 '409': description: Conflict content: *ref_104 '415': description: Unsupported media type content: *ref_105 '500': description: An error has occured content: *ref_14 /cards/balance: post: tags: - Cards summary: View EBT balance operationId: balanceCard description: | Use this method to view the balance of an Electronic Benefit Transfer (EBT) card. If the request is successful, our gateway returns the current balance of an EBT card. requestBody: content: application/json: schema: required: &ref_756 - card - currency - processingTerminalId type: object properties: &ref_757 processingTerminalId: maxLength: 50 minLength: 4 type: string description: Unique identifier that we assigned to the terminal. example: '1234001' operator: maxLength: 50 minLength: 0 type: string description: Operator who requested the balance inquiry. example: Jane currency: type: string description: Currency of the transaction. The value for the currency follows the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard. enum: *ref_83 customer: type: object description: Object that contains the customer's contact details and address information. properties: *ref_176 card: type: object description: "Polymorphic object that contains payment details. \n\nThe value of the type parameter determines which variant you should use: \n-\t`card` - Payment card details\n-\t`singleUseToken` - Single-use token details\n" discriminator: propertyName: type mapping: card: '#/components/schemas/cardPayload' singleUseToken: '#/components/schemas/singleUseTokenPayload' oneOf: - required: *ref_167 type: object writeOnly: true title: card description: Object that contains information about the customer’s payment card. properties: *ref_168 - required: *ref_181 type: object writeOnly: true title: singleUseToken description: Object that contains information about the single-use token, which represents the customer’s payment details. properties: *ref_182 examples: cardBalanceRequest: summary: Card Balance description: Card Balance value: &ref_985 operator: Jane processingTerminalId: '1234001' currency: USD card: type: card cardDetails: entryMethod: keyed cardholderName: Sarah Hazel Hopper cardholderSignature: a1b1c012345678a000b000c0012345d0e0f010g10061a031i001j071k0a1b0c1d0e1234567890120f1g0h1i0j1k0a1b0123451c012d0e1f0g1h0i1j123k1a1b1c1d1e1f1g123h1i1j1k1a1b1c1d1e1f1g123h123i1j123k12340a120a12345b012c0123012d0d1e0f1g0h1i123j123k10000 keyedData: dataFormat: plainText cardNumber: '4539858876047062' expiryDate: '1230' device: model: paxA920 dataKsn: FFFF5B09910001000061 firmwareVersion: PayDroid_8.1.0_Sagittarius_V11.1.11_20200904 V1.04.02_20210617 category: attended serialNumber: '1850010868' pinDetails: dataFormat: dukpt pin: 0123456789abcdef pinKsn: 0002152304aad1234561 ebtDetails: benefitCategory: cash required: true responses: '200': description: Successful request. Returns the current balance of the EBT card. content: application/json: schema: required: &ref_758 - card - processingTerminalId type: object properties: &ref_759 processingTerminalId: maxLength: 50 minLength: 4 type: string description: Unique identifier that we assigned to the terminal. example: '1234001' operator: maxLength: 50 minLength: 0 type: string description: Operator who requested the balance inquiry. example: Jane card: required: *ref_256 type: object description: Object that contains the details of the payment card. properties: *ref_257 responseCode: type: string 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. enum: - A - D - E - P - R - C responseMessage: maxLength: 48 minLength: 1 type: string description: Response description from the payment processor, for example, Refer to Card Issuer. example: Refer to Card Issuer examples: cardBalanceResponse: summary: Card Balance description: Card Balance value: &ref_986 operator: Jane processingTerminalId: '1234001' card: type: Common Benefit Identification Card entryMethod: keyed cardholderName: Sarah Hazel Hopper cardholderSignature: a1b1c012345678a000b000c0012345d0e0f010g10061a031i001j071k0a1b0c1d0e1234567890120f1g0h1i0j1k0a1b0123451c012d0e1f0g1h0i1j123k1a1b1c1d1e1f1g123h1i1j1k1a1b1c1d1e1f1g123h123i1j123k12340a120a12345b012c0123012d0d1e0f1g0h1i123j123k10000 cardNumber: 453985******7062 expiryDate: '1230' balances: - benefitCategory: cash amount: 10000 currency: USD responseCode: A responseMessage: Approved '400': description: Invalid request content: *ref_15 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '404': description: Resource not found content: *ref_18 '406': description: Not acceptable content: *ref_19 '409': description: Conflict content: *ref_104 '415': description: Unsupported media type content: *ref_105 '500': description: An error has occured content: *ref_14 /cards/bin-lookup: post: tags: - Cards summary: Look up BIN information description: | Use this method to retrieve information about a debit card, a credit card, or an EBT card. If you apply surcharges to transactions, you can also check if the card supports surcharging. In the response, our gateway returns the following information about the card: - **Card details** - Information about the card, for example, the issuing bank and the masked card number. - **Surcharging information** - If you apply a surcharge to transactions, our gateway checks that the card supports surcharging and returns information about the surcharge. For more information about surcharging, go to [Credit card surcharging](https://docs.payroc.com/knowledge/card-payments/credit-card-surcharging). operationId: binLookup requestBody: content: application/json: schema: required: &ref_762 - card type: object properties: &ref_763 processingTerminalId: maxLength: 50 minLength: 4 type: string description: Unique identifier that we assigned to the terminal. example: '1234001' amount: exclusiveMinimum: 0 type: integer format: int64 description: Transaction amount that you send to check the surcharge amount. The value is in the currency's lowest denomination, for example, cents. currency: type: string description: Currency of the transaction. The value for the currency follows the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard. enum: *ref_83 card: type: object description: "Polymorphic object that contains payment details. \n\nThe value of the type parameter determines which variant you should use: \n-\t`card` - Payment card details\n-\t`cardBin` - Bank identification number (BIN) of the payment card\n-\t`secureToken` - Secure token details\n-\t`digitalWallet` - Digital wallet details\n" discriminator: propertyName: type mapping: card: '#/components/schemas/cardPayload' cardBin: '#/components/schemas/cardBinPayload' secureToken: '#/components/schemas/secureTokenPayload' digitalWallet: '#/components/schemas/digitalWalletPayload' oneOf: - required: *ref_167 type: object writeOnly: true title: card description: Object that contains information about the customer’s payment card. properties: *ref_168 - required: &ref_760 - type - bin type: object writeOnly: true title: cardBin description: Object that contains information about the card's bank identification number (BIN). properties: &ref_761 type: type: string description: Method that the terminal used to take the payment. enum: - cardBin example: cardBin bin: maxLength: 12 minLength: 6 type: string example: '123456789012' - required: *ref_179 type: object writeOnly: true title: secureToken description: Object that contains information about the secure token that represents the customer’s payment details. properties: *ref_180 - required: *ref_258 type: object writeOnly: true title: digitalWallet description: Object that contains information about the payment details in the customer’s digital wallet. properties: *ref_259 examples: binLookupRequest: summary: BIN lookup description: BIN lookup value: &ref_987 operator: Jane processingTerminalId: '1234001' card: type: card cardDetails: entryMethod: keyed cardholderName: Sarah Hazel Hopper cardholderSignature: a1b1c012345678a000b000c0012345d0e0f010g10061a031i001j071k0a1b0c1d0e1234567890120f1g0h1i0j1k0a1b0123451c012d0e1f0g1h0i1j123k1a1b1c1d1e1f1g123h1i1j1k1a1b1c1d1e1f1g123h123i1j123k12340a120a12345b012c0123012d0d1e0f1g0h1i123j123k10000 keyedData: dataFormat: plainText cardNumber: '4539858876047062' expiryDate: '1230' required: true responses: '200': description: Successful request. Returns the BIN information. content: application/json: schema: required: &ref_262 - type - cardNumber type: object readOnly: true properties: &ref_263 type: type: string description: Card brand of the card, for example, Visa. cardNumber: maxLength: 19 minLength: 12 type: string description: Masked card number. Our gateway shows only the first six digits and the last four digits of the card number, for example, 548010******5929. country: type: string format: iso-3166-1 description: Country of the issuing bank. The value for the country follows the [ISO-3166-1](https://www.iso.org/iso-3166-country-codes.html) standard. currency: type: string description: Currency of the transaction. The value for the currency follows the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard. enum: *ref_83 debit: type: boolean description: Indicates if the card is a debit card. surcharging: required: *ref_260 type: object description: Object that contains surcharge information. Our gateway returns this object only if the merchant adds a surcharge to transactions. properties: *ref_261 description: Object that contains information about the card. examples: binLookupResponse: summary: BIN lookup description: BIN lookup value: &ref_988 type: MASTERCARD cardNumber: 453985******7062 country: US currency: USD debit: false '400': description: Invalid request content: *ref_15 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '404': description: Resource not found content: *ref_18 '406': description: Not acceptable content: *ref_19 '409': description: Conflict content: *ref_104 '415': description: Unsupported media type content: *ref_105 '500': description: An error has occured content: *ref_14 /fx-rates: post: tags: - Currency conversion summary: Verify DCC eligibility description: | > **Important:** There are restrictions on which merchants can use this method. For more information, go to [Dynamic Currency Conversion](https://docs.payroc.com/knowledge/card-payments/dynamic-currency-conversion). Use this method to check if a card is eligible for Dynamic Currency Conversion (DCC) and to retrieve the conversion rate for a transaction amount. DCC provides a customer with the option to use their card's currency instead of the merchant's currency, for example, in Ireland, an American customer can pay in US dollars instead of Euros. The request includes the following: - **Payment method** - Card information, a secure token, or digital wallet. - **Transaction information** - Amount and currency of the transaction in the merchant's currency. If the card is eligible for DCC, our gateway returns the transaction amount in the card's currency and a dccOffer object that contains information about the conversion rate. The dccOffer object contains the following fields that you need when you [run a sale](https://docs.payroc.com/api/schema/card-payments/payments/create) or [unreferenced refund](https://docs.payroc.com/api/schema/card-payments/refunds/create-unreferenced-refund) with DCC: - fxAmount - fxCurrency - fxRate - markup - accepted - offerReference operationId: getFxRates requestBody: content: application/json: schema: required: &ref_764 - baseAmount - baseCurrency - channel - paymentMethod - processingTerminalId type: object properties: &ref_765 channel: description: Channel that the merchant used to receive payment details for the transaction. type: string enum: - pos - web - moto example: pos processingTerminalId: maxLength: 50 minLength: 4 type: string description: Unique identifier that we assigned to the terminal. example: '1234001' operator: maxLength: 50 minLength: 1 type: string description: Operator who ran the transaction. example: Jane baseAmount: exclusiveMinimum: 0 type: integer format: int64 description: Total amount of the transaction in the merchant’s currency. The value is in the currency’s lowest denomination, for example, cents. baseCurrency: type: string description: Currency of the transaction. The value for the currency follows the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard. enum: *ref_83 paymentMethod: type: object description: "Polymorphic object that contains payment details. \n\nThe value of the type parameter determines which variant you should use: \n-\t`card` - Payment card details\n-\t`secureToken` - Secure token details\n-\t`digitalWallet` - Digital wallet details\n" discriminator: propertyName: type mapping: card: '#/components/schemas/cardPayload' secureToken: '#/components/schemas/secureTokenPayload' digitalWallet: '#/components/schemas/digitalWalletPayload' oneOf: - required: *ref_167 type: object writeOnly: true title: card description: Object that contains information about the customer’s payment card. properties: *ref_168 - required: *ref_179 type: object writeOnly: true title: secureToken description: Object that contains information about the secure token that represents the customer’s payment details. properties: *ref_180 - required: *ref_258 type: object writeOnly: true title: digitalWallet description: Object that contains information about the payment details in the customer’s digital wallet. properties: *ref_259 examples: fxRateRequest: summary: Fx-Rate description: Fx-Rate value: &ref_989 channel: web operator: Jane processingTerminalId: '1234001' baseAmount: 10000 baseCurrency: USD paymentMethod: type: card accountType: checking cardDetails: entryMethod: keyed cardholderName: Sarah Hazel Hopper keyedData: dataFormat: plainText cardNumber: '4539858876047062' expiryDate: '1230' required: true responses: '200': description: Successful request. Returns the currency conversion rate for the transaction. content: application/json: schema: required: &ref_768 - baseAmount - baseCurrency - cardInfo - inquiryResult - processingTerminalId type: object description: Foreign exchange rate for the transaction. properties: &ref_769 processingTerminalId: maxLength: 50 minLength: 4 type: string description: Unique identifier that we assigned to the terminal. example: '1234001' operator: maxLength: 50 minLength: 0 type: string description: Operator who ran the transaction. example: Jane baseAmount: exclusiveMinimum: 0 type: integer format: int64 description: Total amount of the transaction in the local currency. The value is in the currency’s lowest denomination, for example, cents. baseCurrency: type: string description: Currency of the transaction. The value for the currency follows the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard. enum: *ref_83 inquiryResult: required: &ref_766 - dccOffered type: object description: Object that indicates if the customer's card is eligible for Dynamic Currency Conversion (DCC). properties: &ref_767 dccOffered: type: boolean default: false description: Indicates if the card is eligible for Dynamic Currency Conversion (DCC). example: false causeOfRejection: type: string description: Explains why the DCC service did not offer a currency conversion rate to the customer. example: Service unavailable dccOffer: required: *ref_227 type: object 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). properties: *ref_228 cardInfo: required: *ref_262 type: object readOnly: true properties: *ref_263 description: Object that contains information about the card. examples: fxRateResponse: summary: Fx-Rate description: Fx-Rate value: &ref_990 processingTerminalId: '1234001' operator: Jane baseAmount: 10000 baseCurrency: EUR inquiryResult: dccOffered: true dccOffer: accepted: true reference: 3396977e-40b9-4b26-8a3f-c25bc1280ee2 fxAmount: 16125 fxCurrency: JPY fxCurrencyCode: '392' fxCurrencyExponent: 0 fxRate: 161.2542 markup: 3 provider: FEXCO source: REUTERS WHOLESALE INTERBANK cardInfo: type: MASTERCARD cardNumber: 453985******7062 '400': description: Invalid request content: *ref_15 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '404': description: Resource not found content: *ref_18 '406': description: Not acceptable content: *ref_19 '409': description: Conflict content: *ref_104 '415': description: Unsupported media type content: *ref_105 '500': description: An error has occured content: *ref_14 /bank-transfer-payments: post: tags: - Bank transfer payments summary: Create payment operationId: bankTransferPayment description: "Use this method to run a sale with a customer's bank account details. \n\nIn the response, our gateway returns information about the bank transfer payment and a paymentId, which you need for the following methods: \n-\t[Retrieve payment](https://docs.payroc.com/api/schema/bank-transfer-payments/payments/retrieve) - View the details of the bank transfer payment.\n-\t[Reverse payment](https://docs.payroc.com/api/schema/bank-transfer-payments/refunds/reverse-payment) - Cancel the bank transfer payment if it's an open batch.\n-\t[Refund payment](https://docs.payroc.com/api/schema/bank-transfer-payments/refunds/refund) - Run a referenced refund to return funds to the customer's bank account.\n\n**Payment methods** \n\nOur gateway accepts the following payment methods: \n-\tAutomated clearing house (ACH) details\n-\tPre-authorized debit (PAD) details \n\nYou can also use [secure tokens](https://docs.payroc.com/api/schema/payments/secure-tokens/overview) and [single-use tokens](https://docs.payroc.com/api/schema/tokenization/single-use-tokens/create) that you created from ACH details or PAD details. \n" parameters: - name: Idempotency-Key in: header required: true 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). schema: *ref_22 examples: *ref_23 requestBody: content: application/json: schema: required: &ref_784 - order - paymentMethod - processingTerminalId type: object description: Object that contains information about the sale and the customer's bank details. properties: &ref_785 processingTerminalId: maxLength: 50 minLength: 4 type: string description: Unique identifier that we assigned to the terminal. example: ready order: required: &ref_782 - amount - currency - orderId type: object allOf: &ref_783 - required: &ref_264 - amount - currency - orderId type: object allOf: &ref_265 - required: *ref_218 type: object description: Object that contains details about the transaction. properties: *ref_219 - type: object properties: orderId: maxLength: 24 minLength: 1 type: string description: A unique identifier assigned by the merchant. example: OrderRef6543 dateTime: type: string format: date-time readOnly: true description: The processing date and time of the transaction represented as per [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) standard. example: '2024-07-02T15:30:00Z' description: maxLength: 256 minLength: 1 type: string description: A brief description of the transaction. example: 'Pizza Doe #1234 - Dinner' amount: type: integer format: int64 description: The total amount in the currency's lowest denomination. For example, cents. example: 4999 currency: type: string description: Currency of the transaction. The value for the currency follows the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard. enum: *ref_83 description: Object that contains information about the transaction. - type: object properties: breakdown: allOf: &ref_779 - required: &ref_266 - subtotal type: object description: Object that contains information about the transaction. properties: &ref_267 subtotal: type: integer format: int64 description: Total amount of the transaction before tax and tip. The value is in the currency's lowest denomination, for example, cents. example: 4500 tip: description: Object that contains tip information for the transaction. required: *ref_211 type: object properties: *ref_212 required: &ref_780 - subtotal type: object description: Object that contains information about the transaction. properties: &ref_781 taxes: type: array description: Array of tax objects. items: type: object required: *ref_170 properties: *ref_171 description: Object that contains information about the transaction. customer: type: object description: Object that contains information about the customer. properties: &ref_268 notificationLanguage: maxLength: 2 minLength: 2 type: string format: iso-639-1 description: Customer's preferred notification language. This code follows the [ISO 639-1](https://www.iso.org/iso-639-language-code) standard. enum: - en - fr example: en contactMethods: uniqueItems: true 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" type: array items: discriminator: *ref_2 oneOf: *ref_3 credentialOnFile: type: object description: Object that contains information about saving the customer’s payment details. properties: *ref_220 paymentMethod: type: object description: "Polymorphic object that contains payment detail information. \n\nThe value of the type parameter determines which variant you should use: \n-\t`ach` - Automated Clearing House (ACH) details\n-\t`pad` - Pre-authorized debit (PAD) details\n-\t`secureToken` - Secure token details\n-\t`singleUseToken` - Single-use token details\n" discriminator: propertyName: type mapping: ach: '#/components/schemas/achPayload' pad: '#/components/schemas/padPayload' secureToken: '#/components/schemas/secureTokenPayload' singleUseToken: '#/components/schemas/singleUseTokenPayload' oneOf: - required: *ref_163 type: object writeOnly: true title: ach description: Object that contains information about the payment details for the customer’s automated clearing house (ACH) transactions. properties: *ref_164 - required: *ref_165 type: object writeOnly: true title: pad description: Object that contains information about the payment details for the customer’s preauthorized electronic debit (PAD) transactions. properties: *ref_166 - required: *ref_179 type: object writeOnly: true title: secureToken description: Object that contains information about the secure token that represents the customer’s payment details. properties: *ref_180 - required: *ref_181 type: object writeOnly: true title: singleUseToken description: Object that contains information about the single-use token, which represents the customer’s payment details. properties: *ref_182 customFields: type: array description: | Array of customField objects. items: required: *ref_129 type: object properties: *ref_130 examples: createdBankTransferPaymentStoreToken: summary: Store Token Bank Transfer Payment description: Bank Transfer Payment with ACH payload and token storage value: &ref_992 processingTerminalId: '1234001' order: orderId: OrderRef6543 description: Large Pepperoni Pizza amount: 4999 currency: USD breakdown: subtotal: 4347 tip: type: percentage percentage: 10 taxes: - type: rate name: Sales Tax rate: 5 customer: notificationLanguage: en contactMethods: - type: email value: joe@blogssoftware.com credentialOnFile: tokenize: true paymentMethod: type: ach accountType: checking nameOnAccount: Sarah Hazel Hopper accountNumber: '11101010' routingNumber: '053200983' secCode: web customFields: - name: yourCustomField value: abc123 required: true responses: '201': description: Successful request. We processed the sale. content: application/json: schema: required: &ref_269 - bankAccount - order - paymentId - processingTerminalId - transactionResult type: object description: Object that contains information about the sale and the customer's bank details. properties: &ref_270 paymentId: maxLength: 10 minLength: 10 type: string description: Unique identifier that we assigned to the payment. example: M2MJOG6O2Y processingTerminalId: maxLength: 50 minLength: 4 type: string description: Unique identifier that we assigned to the terminal. example: '1234001' order: required: &ref_773 - amount - currency - orderId type: object allOf: &ref_774 - required: *ref_264 type: object allOf: *ref_265 description: Object that contains information about the transaction. - type: object properties: breakdown: allOf: &ref_770 - required: *ref_266 type: object description: Object that contains information about the transaction. properties: *ref_267 required: &ref_771 - subtotal type: object description: Object that contains information about the transaction. properties: &ref_772 taxes: type: array description: Array of tax objects. items: required: *ref_124 type: object properties: *ref_125 description: Object that contains information about the transaction. customer: type: object description: Object that contains information about the customer. properties: *ref_268 bankAccount: description: "Polymorphic object that contains bank account information. \nThe value of the type field determines which variant you should use: \n-\t`ach` - Automated Clearing House (ACH) details\n-\t`pad` - Pre-authorized debit (PAD) details\n" type: object discriminator: propertyName: type mapping: ach: '#/components/schemas/achBankAccount' pad: '#/components/schemas/padBankAccount' oneOf: - required: &ref_276 - accountNumber - nameOnAccount - routingNumber - type type: object title: ach description: Object that contains the customer's account details. properties: &ref_277 type: type: string enum: - ach example: ach secCode: type: string description: | Indicates the type of authorization for the transaction. **Note:** The field is mandatory for ACH secure token. - `web` – Online transaction. - `tel` – Telephone transaction. - `ccd` – Corporate credit card or debit card transaction. - `ppd` – Pre-arranged transaction. enum: - web - tel - ccd - ppd example: web nameOnAccount: maxLength: 50 minLength: 1 type: string description: Customer's name. example: Sarah Hazel Hopper accountNumber: maxLength: 17 minLength: 4 type: string description: Customer's bank account number. We mask all digits except the last four digits. example: '123456789' routingNumber: maxLength: 9 minLength: 9 type: string description: | Routing number of the customer’s account. **Note:** In responses, our gateway shows only the last four digits of the account's routing number, for example, *****4162. example: '123456789' secureToken: required: *ref_138 type: object description: Object that contains information about the secure token. properties: *ref_139 - required: &ref_278 - accountNumber - institutionNumber - nameOnAccount - transitNumber - type type: object title: pad description: Object that contains the customer's account details. properties: &ref_279 type: type: string enum: - pad example: pad nameOnAccount: maxLength: 29 minLength: 1 type: string description: Customer's name. example: Sarah Hazel Hopper accountNumber: maxLength: 12 minLength: 7 type: string description: Customer's bank account number. We mask all digits except the last four digits. example: '1234567890' transitNumber: maxLength: 5 minLength: 5 type: string description: Five-digit code that represents the customer's banking branch. example: '76543' institutionNumber: maxLength: 3 minLength: 3 type: string description: Three-digit code that represents the customer's bank. example: '543' secureToken: required: *ref_138 type: object description: Object that contains information about the secure token. properties: *ref_139 refunds: type: array uniqueItems: true description: List of refunds issued against the payment. items: required: *ref_200 type: object description: Object that contains information about a refund. properties: *ref_201 returns: type: array uniqueItems: true description: List of returns issued against the payment. items: required: &ref_775 - date - paymentId - represented - returnCode - returnReason type: object description: Object that contains information about a return. properties: &ref_776 paymentId: maxLength: 10 minLength: 10 type: string description: Unique identifier that our gateway assigned to the payment. example: M2MJOG6O2Y date: type: string format: date description: The date that the check was returned. example: '2024-07-02' returnCode: type: string description: The NACHA return code. example: R11 returnReason: type: string description: The reason why the check was returned. example: Customer advises not authorized represented: type: boolean description: Indicates whether the return has been re-presented. example: false link: type: object readOnly: true description: Object that contains HATEOAS links for the resource. properties: *ref_4 required: *ref_5 example: *ref_6 representment: description: List of re-presented payments linked to the return. required: *ref_233 type: object properties: *ref_234 transactionResult: type: object description: Object that contains information about the transaction. required: &ref_280 - responseMessage - status - type readOnly: true properties: &ref_281 type: type: string description: Type of transaction. enum: - payment - refund - unreferencedRefund - accountVerification example: payment status: type: string description: Status of the transaction. enum: - ready - pending - declined - complete - admin - reversal - returned example: complete authorizedAmount: type: number description: | Amount of the transaction. **Note:** The amount is negative for a refund. example: 2899 currency: type: string description: Currency of the transaction. The value for the currency follows the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard. enum: *ref_83 responseCode: type: string description: | Response from the processor. - `A` - The processor approved the transaction. - `D` - The processor declined the transaction. example: A responseMessage: maxLength: 48 minLength: 1 type: string description: Description of the response from the processor. example: Payment Approved processorResponseCode: type: string description: Original response code that the processor sent. example: A customFields: type: array description: | Array of customField objects. items: required: *ref_129 type: object properties: *ref_130 examples: createdBankTransferPaymentStoreToken: summary: Store Token Bank Transfer Payment description: Bank Transfer Payment with ACH payload and token storage value: &ref_271 paymentId: M2MJOG6O2Y processingTerminalId: '1234001' order: orderId: OrderRef6543 dateTime: '2024-07-02T15:30:00Z' description: Large Pepperoni Pizza amount: 4999 currency: USD breakdown: subtotal: 4347 tip: type: percentage amount: 435 percentage: 10 taxes: - name: Sales Tax rate: 5 amount: 217 customer: contactMethods: - type: email value: sarah.hopper@example.com notificationLanguage: en bankAccount: type: ach secCode: web accountType: checking nameOnAccount: Sarah Hazel Hopper accountNumber: '****3159' routingNumber: '053200983' secureToken: secureTokenId: MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa customerName: Sarah Hazel Hopper token: '296753123456' status: notValidated link: rel: self method: GET href: https://api.payroc.com/v1/processing-terminals/1234001/secure-tokens/MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa transactionResult: type: payment status: ready authorizedAmount: 4999 currency: USD responseCode: A responseMessage: NoError processorResponseCode: '0' customFields: - name: yourCustomField value: abc123 headers: location: description: URI reference to created resource. schema: *ref_24 examples: *ref_25 '400': description: Validation error content: application/problem+json: schema: type: object properties: *ref_9 required: *ref_10 examples: validationError: summary: Bad Request description: One or more validation errors occurred value: *ref_11 idempotentKeyMissing: summary: Idempotency key missing description: Idempotency key must be supplied value: *ref_26 idempotentKeyInUse: summary: Idempotency key in use description: Idempotency key in use value: *ref_29 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '406': description: Not acceptable content: *ref_19 '409': description: Conflict content: *ref_104 '415': description: Unsupported media type content: *ref_105 '500': description: An error has occured content: *ref_14 get: tags: - Bank transfer payments summary: List payments description: | Use this method to return a [paginated](https://docs.payroc.com/api/pagination) list of payments. **Note:** If you want to view the details of a specific payment and you have its paymentId, use our [Retrieve Payment](https://docs.payroc.com/api/schema/bank-transfer-payments/payments/retrieve) method. Use query parameters to filter the list of results that we return, for example, to search for payments for a customer, a date range, or a settlement state. Our gateway returns the following information about each payment in the list: - Order details, including the transaction amount and when it was processed. - Bank account details, including the customer’s name and account number. - Customer's details, including the customer’s phone number. - Transaction details, including any refunds or re-presentments. For each transaction, we also return the paymentId and an optional secureTokenId, which you can use to perform follow-on actions. operationId: listBankTransferPayments parameters: - name: processingTerminalId in: query required: true description: Filter results by the unique identifier that we assigned to the terminal. schema: &ref_471 maxLength: 50 minLength: 4 type: string examples: &ref_472 example: value: '1234001' - name: orderId in: query description: Filter results by the order ID of the payment. schema: &ref_473 maxLength: 24 minLength: 1 type: string examples: &ref_474 example: value: OrderRef6543 - name: nameOnAccount in: query description: Filter results by the account holder's name. schema: &ref_475 maxLength: 50 minLength: 1 type: string examples: &ref_476 example: value: Sarah%20Hazel%20Hopper - name: last4 in: query description: Filter results by the last four digits of the account number. schema: &ref_477 pattern: '[0-9]{4}' type: string examples: &ref_478 example: value: '7890' - name: type in: query description: Filter results by transaction type. schema: &ref_479 type: array items: type: string enum: - payment - accountVerification examples: &ref_480 example: value: - payment - name: status in: query description: Filter results by the status of the payment. schema: &ref_481 type: array items: type: string enum: - ready - pending - declined - complete - admin - reversal - returned examples: &ref_482 example: value: - ready - name: dateFrom in: query description: Filter results by payments that the merchant ran after a specific date. The value follows the [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) standard. schema: &ref_483 type: string format: date-time examples: &ref_484 example: value: '2024-07-01T00:00:00Z' - name: dateTo in: query description: Filter results by payments that the merchant ran before a specific date. The value follows the [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) standard. schema: &ref_485 type: string format: date-time examples: &ref_486 example: value: '2024-07-31T23:59:59Z' - name: settlementState in: query description: Filter results by the settlement status. schema: &ref_487 type: string enum: - settled - unsettled examples: &ref_488 example: value: settled - name: settlementDate in: query description: Filter results by the settlement date. Send a value in **YYYY-MM-DD** format. schema: &ref_489 type: string format: date examples: &ref_490 example: value: '2024-07-15' - name: paymentLinkId in: query description: Filter results by the paymentLinkId. schema: &ref_491 maxLength: 10 minLength: 10 type: string examples: &ref_492 example: value: JZURRJBUPS - name: before in: query description: | Return the previous page of results before the value that you specify. You can’t send the before parameter in the same request as the after parameter. schema: *ref_32 examples: *ref_33 - name: after in: query description: | Return the next page of results after the value that you specify. You can’t send the after parameter in the same request as the before parameter. schema: *ref_34 examples: *ref_35 - name: limit in: query description: Limit the maximum number of results that we return for each page. schema: *ref_36 examples: *ref_37 responses: '200': description: Successful request. Returns a list of payments. content: application/json: schema: required: &ref_777 - count - data - hasMore - limit type: object allOf: &ref_778 - type: object description: Contains the pagination properties that you use to navigate through a list of results. properties: *ref_38 - type: object properties: data: type: array description: Array of payments. items: required: *ref_269 type: object description: Object that contains information about the sale and the customer's bank details. properties: *ref_270 examples: paginatedResults: summary: Bank Transfer Payment description: Bank Transfer Payment value: &ref_991 limit: 2 count: 2 hasMore: true data: - paymentId: M2MJOG6O2Y processingTerminalId: '1234001' order: orderId: OrderRef6543 dateTime: '2024-07-02T15:30:00Z' description: Large Pepperoni Pizza amount: 4999 currency: USD breakdown: subtotal: 4347 tip: type: percentage amount: 435 percentage: 10 taxes: - name: Sales Tax rate: 5 amount: 217 customer: contactMethods: - type: email value: sarah.hopper@example.com notificationLanguage: en bankAccount: type: pad nameOnAccount: Sarah Hazel Hopper accountNumber: '*******3159' transitNumber: '76543' institutionNumber: '543' transactionResult: type: payment status: ready authorizedAmount: 4999 currency: USD responseCode: A - paymentId: E29U8OU8Q4 processingTerminalId: '1234001' order: orderId: OrderRef7654 dateTime: '2024-07-02T15:30:00Z' description: test amount: 3999 currency: USD breakdown: subtotal: 3477 tip: type: percentage amount: 348 percentage: 10 taxes: - name: Sales Tax rate: 5 amount: 174 customer: contactMethods: - type: email value: sarah.hopper@example.com notificationLanguage: en bankAccount: type: pad nameOnAccount: Sarah Hazel Hopper accountNumber: '*******7890' transitNumber: '76543' institutionNumber: '543' transactionResult: type: payment status: ready authorizedAmount: 3999 currency: USD responseCode: A customFields: - name: yourCustomField value: abc123 links: - rel: next method: get href: https://api.payroc.com/v1/bank-transfer-payments?limit=2&processingTerminalId=1234001&after=E29U8OU8Q4 - rel: previous method: get href: https://api.payroc.com/v1//bank-transfer-payments?limit=2&processingTerminalId=1234001&before=M2MJOG6O2Y noActivity: summary: No records found description: Valid request, but no records match the criteria. value: *ref_55 '400': description: Invalid request content: *ref_15 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '406': description: Not acceptable content: *ref_19 '500': description: An error has occured content: *ref_14 /bank-transfer-payments/{paymentId}: get: tags: - Bank transfer payments summary: Retrieve payment description: "Use this method to retrieve information about a bank transfer payment. \n\nTo 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/bank-transfer-payments/payments/create) method. \n\nNote: If you don’t have the paymentId, use our [List Payments](https://docs.payroc.com/api/schema/bank-transfer-payments/payments/list) method to search for the payment. \n\nOur gateway returns the following information about the payment: \n\n-\tOrder details, including the transaction amount and when it was processed. \n-\tBank account details, including the customer’s name and account number. \n-\tCustomer’s details, including the customer’s phone number. \n-\tTransaction details, including any refunds or re-presentments. \n\nIf the merchant saved the customer’s bank account details, our gateway returns a secureTokenID, which you can use to perform follow-on actions.\n" operationId: getBankTransferPayment parameters: - name: paymentId description: Unique identifier that our gateway assigned to the payment. in: path required: true schema: &ref_272 maxLength: 10 minLength: 10 type: string examples: &ref_273 example: value: M2MJOG6O2Y responses: '200': description: Successful request. Returns the specific payment. content: application/json: schema: required: *ref_269 type: object description: Object that contains information about the sale and the customer's bank details. properties: *ref_270 examples: bankTransferPayment: summary: Store Token Bank Transfer Payment description: Bank Transfer Payment with ACH payload and token storage value: *ref_271 bankTransferPaymentDeclined: summary: Declined Payment description: Bank Transfer Payment that was declined with return information value: &ref_993 paymentId: E29U8OU8Q4 processingTerminalId: '1234001' order: orderId: OrderRef7654 dateTime: '2024-07-02T15:30:00Z' description: Large Pepperoni Pizza amount: 4999 currency: USD breakdown: subtotal: 4347 tip: type: percentage amount: 435 percentage: 10 taxes: - name: Sales Tax rate: 5 amount: 217 customer: contactMethods: - type: email value: sarah.hopper@example.com notificationLanguage: en bankAccount: type: ach secCode: web accountType: checking nameOnAccount: Sarah Hazel Hopper accountNumber: '****1591' routingNumber: '053200983' returns: - paymentId: M2MJOG6O2Y date: '2024-07-02' returnCode: R11 returnReason: Customer advises not authorized represented: false link: rel: self method: GET href: https://api.payroc.com/v1/bank-transfer-payments/M2MJOG6O2Y transactionResult: type: payment status: declined authorizedAmount: 4999 currency: USD responseCode: D responseMessage: Payment Declined processorResponseCode: R11 '400': description: Invalid request content: *ref_15 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '404': description: Resource not found content: *ref_18 '406': description: Not acceptable content: *ref_19 '500': description: An error has occured content: *ref_14 /bank-transfer-payments/{paymentId}/reverse: post: tags: - Bank transfer payments summary: Reverse payment description: | Use this method to cancel a bank transfer payment in an open batch. This is also known as voiding a payment. To cancel a bank transfer payment, you need its paymentId. Our gateway returned the paymentId in the response of the [Create Payment](https://docs.payroc.com/api/schema/bank-transfer-payments/payments/create) method. **Note:** If you don't have the paymentId, use our [List Payments](https://docs.payroc.com/api/schema/bank-transfer-payments/payments/list) method to search for the bank transfer payment. If your request is successful, our gateway removes the bank transfer payment from the merchant’s open batch and no funds are taken from the customer's bank account. operationId: reverseBankTransferPayment parameters: - name: Idempotency-Key in: header required: true 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). schema: *ref_22 examples: *ref_23 - name: paymentId description: Unique identifier that our gateway assigned to the payment. in: path required: true schema: *ref_272 examples: *ref_273 responses: '200': description: Successful request. We voided the payment. content: application/json: schema: required: *ref_269 type: object description: Object that contains information about the sale and the customer's bank details. properties: *ref_270 examples: reverseBankTransferPayment: summary: Reverse Bank Transfer Payment description: Reverse Bank Transfer Payment value: &ref_994 paymentId: M2MJOG6O2Y processingTerminalId: '1234001' order: orderId: OrderRef6543 dateTime: '2024-07-02T15:30:00Z' description: Large Pepperoni Pizza amount: 4999 currency: USD breakdown: subtotal: 4347 tip: type: percentage percentage: 10 taxes: - name: VAT rate: 5 amount: 217 customer: contactMethods: - type: email value: sarah.hopper@example.com notificationLanguage: en bankAccount: type: pad nameOnAccount: Sarah Hazel Hopper accountNumber: '*******7890' transitNumber: '76543' institutionNumber: '543' transactionResult: type: payment status: reversal authorizedAmount: 4999 currency: USD responseCode: A customFields: - name: yourCustomField value: abc123 '400': description: Validation error content: application/problem+json: schema: type: object properties: *ref_9 required: *ref_10 examples: validationError: summary: Bad Request description: One or more validation errors occurred value: *ref_11 idempotentKeyMissing: summary: Idempotency key missing description: Idempotency key must be supplied value: *ref_26 idempotentKeyInUse: summary: Idempotency key in use description: Idempotency key in use value: *ref_29 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '404': description: Resource not found content: *ref_18 '406': description: Not acceptable content: *ref_19 '409': description: Conflict content: *ref_104 '415': description: Unsupported media type content: *ref_105 '500': description: An error has occured content: *ref_14 /bank-transfer-payments/{paymentId}/refund: post: tags: - Bank transfer payments summary: Create referenced refund description: | Use this method to refund a bank transfer payment that is in a closed batch. To refund a bank transfer payment, you need its paymentId. Our gateway returned the paymentId in the response of the [Create Payment](https://docs.payroc.com/api/schema/bank-transfer-payments/payments/create) method. **Note:** If you don’t have the paymentId, use our [List Payments](https://docs.payroc.com/api/schema/bank-transfer-payments/payments/list) method to search for the bank transfer payment. If your refund is successful, our gateway returns the payment amount to the customer's account. **Things to consider** - If the merchant refunds a bank transfer payment that is in an open batch, our gateway reverses the bank transfer payment. - Some merchants can run unreferenced refunds, which means that they don’t need a paymentId to return an amount to a customer. For more information about how to run an unreferenced refund, go to [Create Refund](https://docs.payroc.com/api/schema/bank-transfer-payments/refunds/create). operationId: refundBankTransferPayment parameters: - name: Idempotency-Key in: header required: true 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). schema: *ref_22 examples: *ref_23 - name: paymentId description: Unique identifier that our gateway assigned to the payment. in: path required: true schema: *ref_272 examples: *ref_273 requestBody: content: application/json: schema: required: &ref_786 - amount - description type: object description: Object that contains information about the payment that you want to refund. properties: &ref_787 amount: type: integer format: int64 description: Total amount of the refund. The value is in the currency's lowest denomination, for example, cents. example: 4999 description: maxLength: 100 minLength: 1 type: string description: Description of the refund. example: Refund for order OrderRef6543 examples: refundBankTransferPayment: summary: Refund Bank Transfer Payment description: Refund Bank Transfer Payment value: &ref_995 amount: 4999 description: amount to refund required: true responses: '200': description: Successful request. We refunded the payment. content: application/json: schema: required: *ref_269 type: object description: Object that contains information about the sale and the customer's bank details. properties: *ref_270 examples: bankTransferPayment: summary: Reverse Bank Transfer Payment description: Reverse Bank Transfer Payment value: &ref_996 paymentId: M2MJOG6O2Y processingTerminalId: '1234001' order: orderId: OrderRef6543 dateTime: '2024-07-02T15:30:00Z' description: Refund for order OrderRef6543 amount: 4999 currency: USD breakdown: subtotal: 4347 tip: type: percentage amount: 435 percentage: 10 taxes: - name: Sales Tax rate: 5 amount: 217 customer: contactMethods: - type: email value: sarah.hopper@example.com notificationLanguage: en bankAccount: type: pad nameOnAccount: Sarah Hazel Hopper accountNumber: '****7890' transitNumber: '76543' institutionNumber: '543' secureToken: secureTokenId: MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa customerName: Sarah Hopper token: '296753123456' status: notValidated link: rel: self method: GET href: https://api.payroc.com/v1/processing-terminals/1234001/secure-tokens/MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa transactionResult: type: payment status: reversal authorizedAmount: 4999 currency: USD responseCode: A customFields: - name: yourCustomField value: abc123 '400': description: Validation error content: application/problem+json: schema: type: object properties: *ref_9 required: *ref_10 examples: validationError: summary: Bad Request description: One or more validation errors occurred value: *ref_11 idempotentKeyMissing: summary: Idempotency key missing description: Idempotency key must be supplied value: *ref_26 idempotentKeyInUse: summary: Idempotency key in use description: Idempotency key in use value: *ref_29 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '404': description: Resource not found content: *ref_18 '406': description: Not acceptable content: *ref_19 '409': description: Conflict content: *ref_104 '415': description: Unsupported media type content: *ref_105 '500': description: An error has occured content: *ref_14 /bank-transfer-payments/{paymentId}/represent: post: tags: - Bank transfer payments summary: Re-present payment description: "Use this method to re-present an ACH payment. \n\nTo re-present a payment, you need the paymentId of the return. To get the paymentId of the return, complete the following steps: \n\n1.\tUse our [Retrieve Payment](https://docs.payroc.com/api/schema/bank-transfer-payments/payments/retrieve) method to view the details of the original payment. \n2.\tFrom the [returns object](https://docs.payroc.com/api/schema/bank-transfer-payments/payments/retrieve#response.body.returns) in the response, get the paymentId of the return. \n\nOur gateway uses the bank account details from the original payment. If you want to update the customer's bank account details, send the new bank account details in the request. \n\nIf your request is successful, our gateway re-presents the payment.\n" operationId: representBankTransferPayment parameters: - name: Idempotency-Key in: header required: true 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). schema: *ref_22 examples: *ref_23 - name: paymentId description: Unique identifier that our gateway assigned to the payment. in: path required: true schema: *ref_272 examples: *ref_273 requestBody: content: application/json: schema: type: object description: Object that contains the paymentMethod object. properties: &ref_788 paymentMethod: type: object description: "Polymorphic object that contains the customer's updated payment details. \n\nThe value of the type parameter determines which variant you should use: \n-\t`ach` - Automated Clearing House (ACH) details\n-\t`secureToken` - Secure token details\n" discriminator: propertyName: type mapping: ach: '#/components/schemas/achPayload' secureToken: '#/components/schemas/secureTokenPayload' oneOf: - required: *ref_163 type: object writeOnly: true title: ach description: Object that contains information about the payment details for the customer’s automated clearing house (ACH) transactions. properties: *ref_164 - required: *ref_179 type: object writeOnly: true title: secureToken description: Object that contains information about the secure token that represents the customer’s payment details. properties: *ref_180 examples: representBankTransferPayment: summary: Representment Bank Transfer Payment description: Representment Bank Transfer Payment value: &ref_997 paymentMethod: type: ach accountType: checking nameOnAccount: Sarah Hopper accountNumber: '11101010' routingNumber: '053200983' secCode: tel responses: '200': description: Successful request. We processed the payment. content: application/json: schema: required: *ref_269 type: object description: Object that contains information about the sale and the customer's bank details. properties: *ref_270 examples: bankTransferPayment: summary: Store Token Bank Transfer Payment description: Bank Transfer Payment with ACH payload and token storage value: *ref_271 '400': description: Validation error content: application/problem+json: schema: type: object properties: *ref_9 required: *ref_10 examples: validationError: summary: Bad Request description: One or more validation errors occurred value: *ref_11 idempotentKeyMissing: summary: Idempotency key missing description: Idempotency key must be supplied value: *ref_26 idempotentKeyInUse: summary: Idempotency key in use description: Idempotency key in use value: *ref_29 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '404': description: Resource not found content: *ref_18 '406': description: Not acceptable content: *ref_19 '409': description: Conflict content: *ref_104 '415': description: Unsupported media type content: *ref_105 '500': description: An error has occured content: *ref_14 /bank-transfer-refunds: post: tags: - Bank transfer refunds summary: Create unreferenced refund operationId: bankTransferUnreferencedRefund parameters: - name: Idempotency-Key in: header required: true 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). schema: *ref_22 examples: *ref_23 description: "Use this method to create an unreferenced refund. An unreferenced refund is a refund that isn’t linked to a bank transfer payment. \n\n**Note:** If you have the paymentId of the payment you want to refund, use our [Refund Payment](https://docs.payroc.com/api/schema/bank-transfer-payments/refunds/refund) method. If you use our Refund Payment method, our gateway sends the refund amount to the customer’s original payment method and links the refund to the payment. \n\nIn the request, you must provide the customer’s payment method and information about the order including the refund amount. \n\nIn the response, our gateway returns information about the refund and a refundId, which you need for the following methods: \n\n-\t[Retrieve refund](https://docs.payroc.com/api/schema/bank-transfer-payments/refunds/retrieve) – View the details of the refund. \n-\t[Reverse refund](https://docs.payroc.com/api/schema/bank-transfer-payments/refunds/reverse-refund) – Cancel the refund if it’s in an open batch. \n" requestBody: content: application/json: schema: required: &ref_791 - order - processingTerminalId - refundMethod type: object properties: &ref_792 processingTerminalId: maxLength: 50 minLength: 4 type: string description: Unique identifier that we assigned to the terminal. example: 52d9b7f7-3b39-4cd6-9acb-1050f8593ec6 order: description: Object that contains information about the order. required: &ref_274 - amount - currency - description - orderId type: object allOf: &ref_275 - required: *ref_218 type: object description: Object that contains details about the transaction. properties: *ref_219 - type: object description: Object that contains information about the transaction. properties: orderId: maxLength: 24 minLength: 1 type: string description: Unique identifier that the merchant assigned to the transaction. example: OrderRef6543 dateTime: type: string format: date-time readOnly: true description: Date and time that we processed the transaction. We return this value in the ISO 8601 format. example: '2024-07-02T15:30:00Z' description: maxLength: 256 minLength: 0 type: string description: Description of the refund. example: 'Pizza Doe #1234 - Dinner' amount: type: integer format: int64 description: Total amount of the transaction. The value is in the currency's lowest denomination, for example, cents. example: 2899 currency: example: USD type: string description: Currency of the transaction. The value for the currency follows the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard. enum: *ref_83 customer: type: object description: Object that contains information about the customer. properties: *ref_268 refundMethod: description: "Polymorphic object that contains payment details for the refund. \n\nThe value of the type parameter determines which variant you should use: \n-\t`ach` - Automated Clearing House (ACH) details\n-\t`secureToken` - Secure token details\n" type: object discriminator: propertyName: type mapping: ach: '#/components/schemas/achPayload' secureToken: '#/components/schemas/secureTokenPayload' oneOf: - required: *ref_163 type: object writeOnly: true title: ach description: Object that contains information about the payment details for the customer’s automated clearing house (ACH) transactions. properties: *ref_164 - required: *ref_179 type: object writeOnly: true title: secureToken description: Object that contains information about the secure token that represents the customer’s payment details. properties: *ref_180 customFields: type: array description: | Array of customField objects. items: required: *ref_129 type: object properties: *ref_130 examples: bankTransferUnreferencedRefundRequest: summary: Bank Transfer Unreferenced Refund description: Bank Transfer Unreferenced Refund value: &ref_999 processingTerminalId: '1234001' order: orderId: OrderRef6543 description: Refund for order OrderRef6543 amount: 4999 currency: USD customer: notificationLanguage: en contactMethods: - type: email value: sarah.hopper@example.com refundMethod: type: ach secCode: web accountType: checking nameOnAccount: Sarah Hazel Hopper accountNumber: '1234567890' routingNumber: '123456789' customFields: - name: yourCustomField value: abc123 required: true responses: '201': description: Successful request. We sent the refund to the customer's bank account. content: application/json: schema: required: &ref_282 - bankAccount - order - processingTerminalId - refundId - transactionResult type: object properties: &ref_283 refundId: maxLength: 10 minLength: 10 type: string description: Unique identifier that our gateway assigned to the refund. example: CD3HN88U9F processingTerminalId: maxLength: 50 minLength: 4 type: string description: Unique identifier that we assigned to the terminal. example: '1234001' order: description: Object that contains information about the order. required: *ref_274 type: object allOf: *ref_275 customer: type: object description: Object that contains information about the customer. properties: *ref_268 bankAccount: description: "Polymorphic object that contains bank account information. \n\nThe value of the type field determines which variant you should use: \n-\t`ach` - Automated Clearing House (ACH) details\n-\t`pad` - Pre-authorized debit (PAD) details\n" type: object discriminator: propertyName: type mapping: ach: '#/components/schemas/achBankAccount' pad: '#/components/schemas/padBankAccount' oneOf: - required: *ref_276 type: object title: ach description: Object that contains the customer's account details. properties: *ref_277 - required: *ref_278 type: object title: pad description: Object that contains the customer's account details. properties: *ref_279 payment: required: *ref_233 type: object description: Object that contains information about a payment. properties: *ref_234 transactionResult: type: object description: Object that contains information about the transaction. required: *ref_280 readOnly: true properties: *ref_281 customFields: type: array description: | Array of customField objects. items: required: *ref_129 type: object properties: *ref_130 examples: bankTransferUnreferencedRefundResponse: summary: Bank Transfer Unreferenced Refund description: Bank Transfer Unreferenced Refund value: &ref_284 refundId: CD3HN88U9F processingTerminalId: '1234001' order: orderId: OrderRef6543 dateTime: '2024-07-02T15:30:00Z' description: Refund for order OrderRef6543 amount: 4999 currency: USD customer: contactMethods: - type: email value: sarah.hopper@example.com notificationLanguage: en bankAccount: type: ach secCode: web accountType: checking nameOnAccount: Sarah Hazel Hopper accountNumber: '****7890' routingNumber: '*****6789' transactionResult: type: unreferencedRefund status: ready authorizedAmount: -4999 currency: USD responseCode: A responseMessage: NoError processorResponseCode: '0' customFields: - name: yourCustomField value: abc123 headers: location: description: URI reference to created resource. schema: *ref_24 examples: *ref_25 '400': description: Validation error content: application/problem+json: schema: type: object properties: *ref_9 required: *ref_10 examples: validationError: summary: Bad Request description: One or more validation errors occurred value: *ref_11 idempotentKeyMissing: summary: Idempotency key missing description: Idempotency key must be supplied value: *ref_26 idempotentKeyInUse: summary: Idempotency key in use description: Idempotency key in use value: *ref_29 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '406': description: Not acceptable content: *ref_19 '409': description: Conflict content: *ref_104 '415': description: Unsupported media type content: *ref_105 '500': description: An error has occured content: *ref_14 get: tags: - Bank transfer refunds summary: List refunds description: "Use this method to return a [paginated](https://docs.payroc.com/api/pagination) list of bank transfer refunds. \n\n**Note:** If you want to view the details of a specific refund and you have its refundId, use our [Retrieve Refund](https://docs.payroc.com/api/schema/bank-transfer-payments/refunds/retrieve) method. \n\nUse query parameters to filter the list of results that we return, for example, to search for refunds for a customer, an orderId, or a date range. \n\nOur gateway returns the following information about each refund in the list: \n\n-\tOrder details, including the refund amount and when it was processed. \n-\tBank account details, including the customer’s name and account number. \n\nFor referenced refunds, our gateway also returns details about the payment that the refund is linked to.\n" operationId: listBankTransferRefunds parameters: - name: processingTerminalId in: query required: true description: Filter results by the unique identifier that we assigned to the terminal. schema: &ref_493 maxLength: 50 minLength: 4 type: string examples: &ref_494 example: value: '1234001' - name: orderId in: query description: Filter results by the order ID of the refund. schema: &ref_495 maxLength: 24 minLength: 1 type: string examples: &ref_496 example: value: OrderRef6543 - name: nameOnAccount in: query description: Filter results by the accountholder's name. schema: &ref_497 maxLength: 50 minLength: 1 type: string examples: &ref_498 example: value: Sarah%20Hazel%20Hopper - name: last4 in: query description: Filter results by the last four digits of the account number. schema: &ref_499 pattern: '[0-9]{4}' type: string examples: &ref_500 example: value: '7062' - name: type description: Filter results by transaction type. in: query schema: &ref_501 type: array items: type: string enum: - refund - unreferencedRefund examples: &ref_502 example: value: - refund - name: status in: query description: Filter results by the status of the refund. schema: &ref_503 type: array items: type: string enum: - ready - pending - declined - complete - admin - reversal - returned examples: &ref_504 example: value: - ready - name: dateFrom in: query description: Filter results by refunds that the merchant ran after a specific date. The value follows the [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) standard. schema: &ref_505 type: string format: date-time examples: &ref_506 example: value: '2024-07-01T00:00:00Z' - name: dateTo in: query description: Filter results by refunds that the merchant ran before a specific date. The value follows the [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) standard. schema: &ref_507 type: string format: date-time examples: &ref_508 example: value: '2024-07-31T23:59:59Z' - name: settlementState in: query description: Filter results by the settlement status. schema: &ref_509 type: string enum: - settled - unsettled examples: &ref_510 example: value: settled - name: settlementDate in: query description: Filter results by the settlement date. Send a value in **YYYY-MM-DD** format. schema: &ref_511 type: string format: date examples: &ref_512 example: value: '2024-07-15' - name: before in: query description: | Return the previous page of results before the value that you specify. You can’t send the before parameter in the same request as the after parameter. schema: *ref_32 examples: *ref_33 - name: after in: query description: | Return the next page of results after the value that you specify. You can’t send the after parameter in the same request as the before parameter. schema: *ref_34 examples: *ref_35 - name: limit in: query description: Limit the maximum number of results that we return for each page. schema: *ref_36 examples: *ref_37 responses: '200': description: Successful request. Returns a list of refund transactions. content: application/json: schema: required: &ref_789 - count - data - hasMore - limit type: object allOf: &ref_790 - type: object description: Contains the pagination properties that you use to navigate through a list of results. properties: *ref_38 - type: object properties: data: type: array description: Array of refund transactions. items: required: *ref_282 type: object properties: *ref_283 examples: paginatedResults: summary: Paginated Bank Transfer Unreferenced Refund description: Paginated Bank Transfer Unreferenced Refund value: &ref_998 limit: 2 count: 2 hasMore: true data: - refundId: CD3HN88U9F processingTerminalId: '1234001' order: orderId: OrderRef6543 dateTime: '2024-07-02T15:30:00Z' description: refund example amount: 4999 currency: USD customer: contactMethods: - type: email value: sarah.hopper@example.com notificationLanguage: en bankAccount: type: ach secCode: web accountType: checking nameOnAccount: Sarah Hazel Hopper accountNumber: '****3159' routingNumber: '*****0277' transactionResult: type: unreferencedRefund status: ready authorizedAmount: -4999 currency: USD responseCode: A responseMessage: NoError processorResponseCode: '0' - refundId: B6ZOFZNVOP processingTerminalId: '1234001' order: orderId: OrderRef7654 dateTime: '2024-07-02T15:30:00Z' description: Refund for order OrderRef7654 amount: 3999 currency: USD customer: contactMethods: - type: email value: sarah.hopper@example.com notificationLanguage: en bankAccount: type: ach secCode: web accountType: checking nameOnAccount: Sarah Hazel Hopper accountNumber: '****3159' routingNumber: '*****0277' transactionResult: type: unreferencedRefund status: ready authorizedAmount: -3999 currency: USD responseCode: A responseMessage: NoError processorResponseCode: '0' customFields: - name: yourCustomField value: abc123 links: - rel: next method: get href: https://api.payroc.com/v1/bank-transfer-refunds?limit=2&processingTerminalId=1234001&after=B6ZOFZNVOP - rel: previous method: get href: https://api.payroc.com/v1/bank-transfer-refunds?processingTerminalId=1234001&limit=2&before=CD3HN88U9F noActivity: summary: No records found description: Valid request, but no records match the criteria. value: *ref_55 '400': description: Invalid request content: *ref_15 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '406': description: Not acceptable content: *ref_19 '500': description: An error has occured content: *ref_14 /bank-transfer-refunds/{refundId}: get: tags: - Bank transfer refunds summary: Retrieve refund operationId: getBankTransferRefund description: | Use this method to retrieve information about a refund. To retrieve a refund, you need its refundId. Our gateway returned the refundId in the response of the [Refund Payment](https://docs.payroc.com/api/schema/bank-transfer-payments/refunds/refund) method or the [Create Refund](https://docs.payroc.com/api/schema/bank-transfer-payments/refunds/create) method. **Note:** If you don’t have the refundId, use our [List Refunds](https://docs.payroc.com/api/schema/bank-transfer-payments/refunds/list) method to search for the refund. Our gateway returns the following information about the refund: - Order details, including the refund amount and when it was processed. - Bank account details, including the customer’s name and account number. If the refund is a referenced refund, our gateway also returns details about the payment that the refund is linked to. parameters: - name: refundId description: Unique identifier that our gateway assigned to the refund. in: path required: true schema: &ref_285 maxLength: 10 minLength: 10 type: string examples: &ref_286 example: value: CD3HN88U9F responses: '200': description: Successful request. Returns the specific refund. content: application/json: schema: required: *ref_282 type: object properties: *ref_283 examples: bankTransferUnreferencedRefund: summary: Bank Transfer Unreferenced Refund description: Bank Transfer Unreferenced Refund value: *ref_284 '400': description: Invalid request content: *ref_15 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '404': description: Resource not found content: *ref_18 '406': description: Not acceptable content: *ref_19 '500': description: An error has occured content: *ref_14 /bank-transfer-refunds/{refundId}/reverse: post: tags: - Bank transfer refunds summary: Reverse refund operationId: reverseBankTransferRefund description: | Use this method to cancel a bank transfer refund in an open batch. To cancel a refund, you need its refundId. Our gateway returned the refundId in the response of the [Refund Payment](https://docs.payroc.com/api/schema/bank-transfer-payments/refunds/refund) or [Create Refund](https://docs.payroc.com/api/schema/bank-transfer-payments/refunds/create) method. **Note:** If you don’t have the refundId, use our [List Refunds](https://docs.payroc.com/api/schema/bank-transfer-payments/refunds/list) method to search for the refund. If your request is successful, the gateway removes the refund from the merchant’s open batch, and no funds are returned to the cardholder’s account. parameters: - name: Idempotency-Key in: header required: true 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). schema: *ref_22 examples: *ref_23 - name: refundId description: Unique identifier that our gateway assigned to the refund. in: path required: true schema: *ref_285 examples: *ref_286 responses: '200': description: Successful request. We reversed the refund transaction. content: application/json: schema: required: *ref_282 type: object properties: *ref_283 examples: bankTransferUnreferencedRefund: summary: Bank Transfer Unreferenced Refund description: Bank Transfer Unreferenced Refund value: &ref_1000 refundId: CD3HN88U9F processingTerminalId: '1234001' order: orderId: OrderRef6543 dateTime: '2024-07-02T15:30:00Z' description: Refund for order OrderRef6543 amount: 4999 currency: USD customer: contactMethods: - type: email value: sarah.hopper@example.com notificationLanguage: en bankAccount: type: ach secCode: web accountType: checking nameOnAccount: Sarah Hazel Hopper accountNumber: '****3159' routingNumber: '*****0277' transactionResult: type: unreferencedRefund status: reversal authorizedAmount: -4999 currency: USD responseCode: A responseMessage: NoError processorResponseCode: '0' customFields: - name: yourCustomField value: abc123 '400': description: Validation error content: application/problem+json: schema: type: object properties: *ref_9 required: *ref_10 examples: validationError: summary: Bad Request description: One or more validation errors occurred value: *ref_11 idempotentKeyMissing: summary: Idempotency key missing description: Idempotency key must be supplied value: *ref_26 idempotentKeyInUse: summary: Idempotency key in use description: Idempotency key in use value: *ref_29 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '404': description: Resource not found content: *ref_18 '406': description: Not acceptable content: *ref_19 '409': description: Conflict content: *ref_104 '415': description: Unsupported media type content: *ref_105 '500': description: An error has occured content: *ref_14 /bank-accounts/verify: post: tags: - Bank accounts summary: Verify bank account operationId: verifyBankAccount description: | Use this method to verify a customer's bank account details. In the request, send the customer's bank account details. Our gateway can verify the following types of bank details: - Automated Clearing House (ACH) details - Pre-Authorized Debit (PAD) details In the response, our gateway indicates if the account details are valid and if you should use them in follow-on actions. parameters: - name: Idempotency-Key in: header required: true 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). schema: *ref_22 examples: *ref_23 requestBody: content: application/json: schema: required: &ref_793 - processingTerminalId - bankAccount type: object properties: &ref_794 processingTerminalId: maxLength: 50 minLength: 4 type: string description: Unique identifier that we assigned to the terminal. example: '1234001' bankAccount: description: "Polymorphic object that contains bank account information. \n\nThe value of the type field determines which variant you should use: \n-\t`ach` - Automated Clearing House (ACH) details\n-\t`pad` - Pre-authorized debit (PAD) details\n" type: object discriminator: propertyName: type mapping: ach: '#/components/schemas/achPayload' pad: '#/components/schemas/padPayload' oneOf: - required: *ref_163 type: object writeOnly: true title: ach description: Object that contains information about the payment details for the customer’s automated clearing house (ACH) transactions. properties: *ref_164 - required: *ref_165 type: object writeOnly: true title: pad description: Object that contains information about the payment details for the customer’s preauthorized electronic debit (PAD) transactions. properties: *ref_166 examples: bankAccountVerificationRequestPad: summary: PAD Bank Account Verification Request description: Bank Account Verification Request for PAD value: &ref_1001 processingTerminalId: '1234001' bankAccount: type: pad accountType: checking nameOnAccount: Sarah Hazel Hopper accountNumber: '1234567890' routingNumber: '123456789' transitNumber: '76543' institutionNumber: '543' bankAccountVerificationRequestAch: summary: ACH Bank Account Verification Request description: Bank Account Verification Request for ACH value: &ref_1002 processingTerminalId: '1234001' bankAccount: type: ach accountType: checking nameOnAccount: Sarah Hazel Hopper accountNumber: '11101010' routingNumber: '053200983' secCode: web required: true responses: '200': description: Successful request. Returns the verification status of the customer's bank account details. content: application/json: schema: required: &ref_795 - processingTerminalId - verified type: object properties: &ref_796 processingTerminalId: maxLength: 50 minLength: 4 type: string description: Unique identifier that we assigned to the terminal. example: '1234001' verified: type: boolean description: | Indicates if the customer's bank account details are valid. - `true` - Account details are valid. - `false` - Account details are not valid. example: true examples: bankAccountVerificationResponse: summary: Bank Account Verification Response description: Bank Account Verification Response value: &ref_1003 processingTerminalId: '1234001' verified: true '400': description: Validation error content: application/problem+json: schema: type: object properties: *ref_9 required: *ref_10 examples: validationError: summary: Bad Request description: One or more validation errors occurred value: *ref_11 idempotentKeyMissing: summary: Idempotency key missing description: Idempotency key must be supplied value: *ref_26 idempotentKeyInUse: summary: Idempotency key in use description: Idempotency key in use value: *ref_29 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '404': description: Resource not found content: *ref_18 '406': description: Not acceptable content: *ref_19 '409': description: Conflict content: *ref_104 '415': description: Unsupported media type content: *ref_105 '500': description: An error has occured content: *ref_14 /merchant-platforms: summary: Provide capabilities to manage a merchant platform. post: tags: - Merchant platforms summary: Create merchant platform description: | Use this method to board a merchant with Payroc. **Note**: This method is part of our Boarding solution. To help you understand how this method works with other Boarding methods, go to [Board a Merchant](https://docs.payroc.com/guides/board-merchants/boarding). In the request, include the following information: - Legal information, including its legal name and address. - Contact information, including the email address for the business. - Processing account information, including the pricing model, owners, and contacts for the processing account. When you send a successful request, we review the merchant's information. After we complete our review and approve the merchant, we assign: - **merchantPlatformId** - Unique identifier for the merchant platform. - **processingAccountId** - Unique identifier for each processing account linked to the merchant platform. You need to keep these to perform follow-on actions, for example, you need the processingAccountId to [order terminals](https://docs.payroc.com/api/schema/boarding/processing-accounts/create-terminal-order) for the processing account. operationId: createMerchant parameters: - name: Idempotency-Key in: header required: true 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). schema: *ref_22 examples: *ref_23 requestBody: content: application/json: schema: type: object title: create merchant platform required: &ref_812 - business - processingAccounts properties: &ref_813 business: type: object description: Object that contains information about the business. title: business required: &ref_291 - name - taxId - contactMethods - addresses - organizationType properties: &ref_292 name: type: string description: Legal name of the business. maxLength: 100 example: Pizza Doe taxId: type: string description: Tax ID of the business. maxLength: 20 example: 12-3456789 organizationType: type: string description: Type of organization. enum: - privateCorporation - publicCorporation - nonProfit - privateLlc - publicLlc - privatePartnership - publicPartnership - soleProprietor example: privateCorporation countryOfOperation: type: string description: Two-digit code for the country that the business operates in. The format follows the [ISO-3166](https://www.iso.org/iso-3166-country-codes.html) standard. enum: - US example: US addresses: type: array minItems: 1 uniqueItems: true description: Array of polymorphic objects that contain address information for the business. items: oneOf: - title: legalAddress required: &ref_799 - type - city - country - address1 - postalCode - state allOf: &ref_800 - type: object description: Type of address. required: &ref_797 - type properties: &ref_798 type: type: string description: Type of address. enum: - legalAddress default: legalAddress - required: *ref_0 type: object title: address description: Object that contains information about the address. properties: *ref_1 contactMethods: type: array minItems: 1 uniqueItems: true description: "Array of polymorphic objects, which contain contact information. \n\n**Note:** You must provide an email address.\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" items: discriminator: *ref_2 oneOf: *ref_3 processingAccounts: description: Array of processingAccounts objects. type: array minItems: 1 items: required: &ref_303 - doingBusinessAs - owners - businessType - merchandiseOrServiceSold - businessStartDate - timezone - address - contactMethods - processing - funding - pricing - signature - categoryCode type: object properties: &ref_304 processingAccountId: type: string description: Unique identifier of the processing account. readOnly: true example: '38765' doingBusinessAs: type: string description: Trading name of the business. maxLength: 100 example: Pizza Doe owners: description: | Collection of individuals that are responsible for a processing account. When you create a processing account, you must indicate at least one owner as either of the following: - **Control prong** - An individual who has a significant equity stake in the business and can make decisions for the processing account. You can add only one control prong to a processing account. - **Authorized signatory** - An individual who doesn't have an equity stake in the business but can make decisions for the processing account. minItems: 1 type: array items: type: object title: owner required: *ref_30 properties: *ref_31 website: type: string description: Website address of the business. maxLength: 128 example: www.example.com businessType: type: string description: Type of business. enum: - retail - restaurant - internet - moto - lodging - notForProfit example: restaurant categoryCode: type: integer format: int32 description: Merchant Category Code (MCC) for the type of business. maxLength: 4 example: 5999 merchandiseOrServiceSold: type: string description: Description of the services or merchandise sold by the business. maxLength: 125 example: Pizza businessStartDate: type: string format: date description: Date that the business was established. The format of the value is **YYYY-MM-DD**. example: '2020-01-01' timezone: description: Time zone for the processing account. enum: &ref_299 - Pacific/Midway - Pacific/Honolulu - America/Anchorage - America/Los_Angeles - America/Denver - America/Phoenix - America/Chicago - America/Indiana/Indianapolis - America/New_York example: America/Chicago maxLength: 28 address: description: Polymorphic object that contains address information for the processing account. type: object oneOf: - required: *ref_0 type: object title: address description: Object that contains information about the address. properties: *ref_1 contactMethods: type: array minItems: 1 description: "Array of polymorphic objects, which contain contact information. \n\n**Note:** You must provide an email address.\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" items: discriminator: *ref_2 oneOf: *ref_3 processing: description: Object that contains information about how we process transactions for the account. type: object title: processing required: &ref_300 - transactionAmounts - monthlyAmounts - volumeBreakdown properties: &ref_301 merchantId: type: string description: Unique identifier that the acquiring platform assigns to the merchant. maxLength: 15 example: '4525644354' readOnly: true transactionAmounts: description: Object that contains information about transaction amounts for the processing account. type: object required: - average - highest properties: average: type: integer format: int32 description: Estimated average transaction amount. The value is in the currency's lowest denomination, for example, cents. You must provide an amount that is greater than zero. example: 5000 highest: type: integer format: int32 description: Estimated maximum transaction amount. The value is in the currency's lowest denomination, for example, cents. You must provide an amount that is greater than zero. example: 10000 monthlyAmounts: description: Object that contains information about the monthly processing amounts for the processing account. type: object required: - average - highest properties: average: type: integer format: int32 description: Estimated average transaction amount each month. The value is in the currency's lowest denomination, for example, cents. You must provide an amount that is greater than zero. example: 50000 highest: type: integer format: int32 description: Estimated maximum transaction amount each month. The value is in the currency's lowest denomination, for example, cents. You must provide an amount that is greater than zero. example: 100000 volumeBreakdown: type: object description: Object that contains information about the types of transactions ran by the processing account. The percentages for transaction types must total 100%. required: - cardPresent - mailOrTelephone - ecommerce properties: cardPresent: description: Estimated percentage of card-present transactions. type: integer format: int32 example: 77 mailOrTelephone: description: Estimated percentage of mail order or telephone transactions. type: integer format: int32 example: 3 ecommerce: description: Estimated percentage of e-Commerce transactions. type: integer format: int32 example: 20 isSeasonal: type: boolean description: Indicates if the processing account runs transactions on a seasonal basis. For example, if the processing account runs transactions during only the winter months, send a value of `true`. example: false monthsOfOperation: type: array description: Months of the year that the processing account runs transactions. maxItems: 12 items: type: string enum: - jan - feb - mar - apr - may - jun - jul - aug - sep - oct - nov - dec example: - jan - feb ach: description: Object that contains information about Automated Clearing House (ACH) transactions. type: object required: - refunds - estimatedMonthlyTransactions - limits properties: naics: type: string description: North American Industry Classification System (NAICS) code. maxLength: 6 example: '5812' previouslyTerminatedForAch: type: boolean default: false description: Indicates if the business or its principals were previously turned down for ACH processing. example: false refunds: description: Object that contains information about the ACH refund policy for the processing account. type: object required: - writtenRefundPolicy properties: writtenRefundPolicy: type: boolean description: Indicates if the business has a written refund policy. default: false example: true refundPolicyUrl: type: string description: URL of the written refund policy. maxLength: 2000 example: www.example.com/refund-poilcy-url estimatedMonthlyTransactions: type: integer description: Estimated maximum number of transactions that the merchant will process in a month. example: 3000 limits: description: Object that contains information about transaction limits for the processing account. type: object required: - singleTransaction - dailyDeposit - monthlyDeposit properties: singleTransaction: type: integer description: Maximum amount allowed for a single debit or credit transaction. The value is in the currency's lowest denomination, for example, cents. example: 10000 dailyDeposit: type: integer description: Maximum amount of total transactions allowed per day. The value is in the currency's lowest denomination, for example, cents. example: 200000 monthlyDeposit: type: integer description: Maximum amount of total transactions allowed per month. The value is in the currency's lowest denomination, for example, cents. example: 6000000 transactionTypes: type: array description: List of transaction types that the processing account supports. uniqueItems: true items: type: string enum: - prearrangedPayment - corpCashDisbursement - telephoneInitiatedPayment - webInitiatedPayment - other example: - prearrangedPayment - other transactionTypesOther: type: string description: If you send a value of `other` for transactionTypes, provide a list of the supported transaction types. maxLength: 100 example: anotherTransactionType cardAcceptance: type: object description: Object that contains information about the types of cards that the processing account accepts. properties: debitOnly: type: boolean default: false description: Indicates if the merchant accepts only debit cards. example: false hsaFsa: type: boolean default: false description: Indicates if the merchant accepts health savings account (HSA) and flexible spending account (FSA) cards. example: false cardsAccepted: type: array description: List of card types the merchant accepts. uniqueItems: true default: - visa - mastercard - discover - amexOptBlue items: type: string enum: - visa - mastercard - discover - amexOptBlue example: - visa - mastercard specialityCards: type: object description: Information about the speciality cards that the merchant accepts. properties: americanExpressDirect: description: Object that indicates if the merchant accepts American Express Direct cards and contains the merchant’s American Express merchant number. type: object properties: enabled: type: boolean default: false description: Indicates if the merchant accepts American Express Direct. example: true merchantNumber: type: string description: If the merchant accepts American Express Direct, provide their American Express merchant number. maxLength: 100 example: abc1234567 electronicBenefitsTransfer: description: Object that indicates if the merchant accepts Electronic Benefits Transfer (EBT) cards and contains the merchant’s Food and Nutrition Services (FNS) number. type: object properties: enabled: type: boolean default: false description: Indicates if the merchant accepts EBT. example: true fnsNumber: type: string description: If the merchant accepts EBT, provide their FNS number. maxLength: 7 example: abc1234 other: description: Object that contains information about other speciality cards that the merchant accepts. type: object properties: wexMerchantNumber: type: string description: If the merchant accepts WEX, provide their WEX merchant number. maxLength: 50 example: abc1234567 voyagerMerchantId: type: string description: If the merchant accepts Voyager, provide their Voyager merchant ID. maxLength: 50 example: abc1234567 fleetMerchantId: type: string description: If the merchant accepts Fleet, provide their Fleet merchant ID. maxLength: 50 example: abc1234567 funding: type: object description: | Object that contains information about the funding schedule of the processing account. allOf: &ref_806 - type: object properties: &ref_302 status: type: string readOnly: true description: Indicates if the processing account can receive funds. enum: - enabled - disabled example: enabled fundingSchedule: type: string description: | Indicates when funds are sent to the funding account. If you send a value of `sameDay` or `nextDay`, provide a value for acceleratedFundingFee. **Note:** If you send a value of `sameday`, funding includes all transactions the merchant ran before the ACH cut-off time. enum: - standard - nextday - sameday example: nextday default: standard acceleratedFundingFee: type: integer description: | Monthly fee in cents for accelerated funding. The value is in the currency's lowest denomination, for example, cents. We apply this fee if the value for fundingSchedule is `sameday` or `nextday`. example: 1999 default: 0 dailyDiscount: type: boolean description: Indicates if we collect fees from the merchant's account each day. example: false - type: object properties: fundingAccounts: description: Array of fundingAccounts objects. minItems: 1 maxItems: 2 writeOnly: true type: array items: required: *ref_20 type: object title: funding account properties: *ref_21 pricing: type: object description: "Polymorphic object that contains pricing information for the processing account. \n\nThe value of the type parameter determines which variant you should use:\n-\t`intent` - Use a pricing agreement template.\n-\t`agreement` - Create a new pricing agreement.\n" discriminator: &ref_810 propertyName: type mapping: intent: '#/components/schemas/pricingTemplate' agreement: '#/components/schemas/pricingAgreement' oneOf: &ref_811 - type: object title: intent required: &ref_807 - type - pricingIntentId properties: &ref_808 type: type: string description: | Type of pricing for the processing account. **Note**: To create a pricing intent, go to [Create Pricing Intent](https://docs.payroc.com/api/schema/boarding/pricing-intents/create). enum: - intent example: intent pricingIntentId: type: string description: Unique identifier of the pricing intent. example: '6123' - type: object title: agreement allOf: &ref_809 - type: object description: Polymorphic object that contains pricing agreement information for the processing account. properties: type: type: string enum: - agreement example: agreement required: - type - oneOf: - type: object title: US pricing agreement version 5.0 description: Object that contains information about U.S. pricing intents for Merchant Processing Agreement (MPA) 5.0. required: *ref_287 properties: *ref_288 signature: type: object description: "Polymorphic object that contains information about how we captured the owner's signature. \n\nThe value of the type parameter determines which variant you should use:\n-\t`requestedViaDirectLink` - Request signature using a link.\n-\t`requestedViaEmail` - Request signature by email.\n" discriminator: &ref_293 propertyName: type mapping: requestedViaDirectLink: '#/components/schemas/signatureByDirectLink' requestedViaEmail: '#/components/schemas/signatureByEmail' oneOf: &ref_294 - description: Object that contains signature information if we captured the merchant’s signature by direct link. title: requestedViaDirectLink type: object required: &ref_801 - type properties: &ref_802 type: type: string description: Method used to capture the owner's signature. enum: - requestedViaDirectLink example: requestedViaDirectLink link: description: Object that contains links to the signed contract. allOf: - type: object readOnly: true description: Object that contains HATEOAS links for the resource. properties: *ref_4 required: *ref_5 example: *ref_6 example: rel: agreement href: https://us.agreementexpress.net/mv2/viewer2.jsp?docId=00000000-0000-0000-0000-000000000000 method: get - description: Object that contains signature information if we captured the merchant’s signature by email. title: requestedViaEmail type: object required: &ref_803 - type properties: &ref_804 type: type: string description: Method used to capture the owner's signature. enum: - requestedViaEmail example: requestedViaEmail contacts: type: array description: Array of contact objects. items: type: object title: contact required: &ref_313 - type - firstName - lastName - identifiers - contactMethods properties: &ref_314 contactId: type: integer description: Unique identifier of the contact. readOnly: true example: 1543 type: type: string description: Type of contact. enum: - manager - representative - others example: manager firstName: type: string description: Contact's first name. example: Jane maxLength: 50 middleName: type: string description: Contact's middle name. example: Helen maxLength: 50 lastName: type: string description: Contact's last name. example: Doe maxLength: 50 identifiers: minItems: 1 type: array description: Array of identifier objects. example: - type: nationalId value: 000-00-4320 items: required: *ref_289 type: object title: identifier properties: *ref_290 contactMethods: type: array minItems: 1 maxItems: 4 uniqueItems: true description: "Array of polymorphic objects, which contain contact information. \n\n**Note:** If you are adding information about an owner, you must provide at least an email address. If you are adding information about a contact, you must provide at least a contact number. \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" items: discriminator: *ref_2 oneOf: *ref_3 metadata: type: object additionalProperties: type: string description: Object that you can send to include custom data in the request. For more information about how to use metadata, go to [Metadata](https://docs.payroc.com/api/metadata). example: customerId: '2345' metadata: type: object additionalProperties: type: string description: Object that you can send to include custom data in the request. example: customerId: '2345' examples: createMerchantPlatform: summary: Create merchant platform description: Create a merchant platform. value: &ref_1005 business: name: Example Corp taxId: 12-3456789 organizationType: privateCorporation countryOfOperation: US addresses: - type: legalAddress address1: 1 Example Ave. address2: Example Address Line 2 address3: Example Address Line 3 city: Chicago state: Illinois country: US postalCode: '60056' contactMethods: - type: email value: jane.doe@example.com processingAccounts: - doingBusinessAs: Pizza Doe owners: - firstName: Jane middleName: Helen lastName: Doe dateOfBirth: '1964-03-22' address: address1: 1 Example Ave. address2: Example Address Line 2 address3: Example Address Line 3 city: Chicago state: Illinois country: US postalCode: '60056' identifiers: - type: nationalId value: 000-00-4320 contactMethods: - type: email value: jane.doe@example.com relationship: equityPercentage: 48.5 title: CFO isControlProng: true isAuthorizedSignatory: false website: www.example.com businessType: restaurant categoryCode: 5999 merchandiseOrServiceSold: Pizza businessStartDate: '2020-01-01' timezone: America/Chicago address: address1: 1 Example Ave. address2: Example Address Line 2 address3: Example Address Line 3 city: Chicago state: Illinois country: US postalCode: '60056' contactMethods: - type: email value: jane.doe@example.com processing: transactionAmounts: average: 5000 highest: 10000 monthlyAmounts: average: 50000 highest: 100000 volumeBreakdown: cardPresent: 77 mailOrTelephone: 3 ecommerce: 20 isSeasonal: true monthsOfOperation: - jan - feb ach: naics: '5812' previouslyTerminatedForAch: false refunds: writtenRefundPolicy: true refundPolicyUrl: www.example.com/refund-poilcy-url estimatedMonthlyTransactions: 3000 limits: singleTransaction: 10000 dailyDeposit: 200000 monthlyDeposit: 6000000 transactionTypes: - prearrangedPayment - other transactionTypesOther: anotherTransactionType cardAcceptance: debitOnly: false hsaFsa: false cardsAccepted: - visa - mastercard specialityCards: americanExpressDirect: enabled: true merchantNumber: abc1234567 electronicBenefitsTransfer: enabled: true fnsNumber: '6789012' other: wexMerchantNumber: abc1234567 voyagerMerchantId: abc1234567 fleetMerchantId: abc1234567 funding: fundingSchedule: nextday acceleratedFundingFee: 1999 dailyDiscount: false fundingAccounts: - type: checking use: creditAndDebit nameOnAccount: Jane Doe paymentMethods: - type: ach value: routingNumber: '123456789' accountNumber: '1234567890' metadata: yourCustomField: abc123 pricing: type: intent pricingIntentId: '6123' signature: type: requestedViaDirectLink contacts: - type: manager firstName: Jane middleName: Helen lastName: Doe identifiers: - type: nationalId value: 000-00-4320 contactMethods: - type: email value: jane.doe@example.com metadata: customerId: '2345' metadata: customerId: '2345' responses: '201': description: Successful request. We created the merchant platform. content: application/json: schema: type: object title: merchant required: &ref_295 - business - processingAccounts properties: &ref_296 merchantPlatformId: type: string readOnly: true description: Unique identifier that we assigned to the merchant platform. example: '12345' createdDate: type: string format: date-time example: '2024-07-02T12:00:00.000Z' readOnly: true description: Date that the merchant platform was created. We return this value in the [ISO-8601](https://www.iso.org/iso-8601-date-and-time-format.html) format. lastModifiedDate: type: string format: date-time example: '2024-07-02T12:00:00.000Z' readOnly: true description: Date that the merchant platform was last modified. We return this value in the [ISO-8601](https://www.iso.org/iso-8601-date-and-time-format.html) format. business: type: object description: Object that contains information about the business. title: business required: *ref_291 properties: *ref_292 processingAccounts: readOnly: true description: Array of processingAccount objects. type: array items: type: object required: - doingBusinessAs - status title: processingAccount properties: processingAccountId: type: string description: Unique identifier that we assigned to the processing account. example: '38765' doingBusinessAs: type: string description: Trading name of the business. example: Pizza Doe status: type: string description: | Status of the processing account. - `entered` - We have received information about the account, but we have not yet reviewed it. - `pending` - We have reviewed the information about the account, but we have not yet approved it. - `approved` - We have approved the account for processing transactions and funding. - `subjectTo` - We have approved the account, but we are waiting on further information. - `dormant` - Account is closed for a period. - `nonProcessing` - We have approved the account, but the merchant has not yet run a transaction. - `rejected` - We rejected the application for the processing account. - `terminated` - Processing account is closed. - `cancelled` - Merchant withdrew the application for the processing account. - `failed` - An error occurred while we were setting up the processing account. **Note**: You can subscribe to our processingAccount.status.changed event to get notifications when we change the status of a processing account. For more information about how to subscribe to events, go to [Event Subscriptions](https://docs.payroc.com/guides/board-merchants/event-subscriptions). readOnly: true enum: - entered - pending - approved - subjectTo - dormant - nonProcessing - rejected - terminated - cancelled - failed example: entered link: type: object description: Object that contains HATEOAS links for the processing account. properties: rel: type: string description: Relationship to the parent resource. example: processingAccount href: type: string description: Link to the resource. example: https://api.payroc.com/v1/processing-accounts/38765 method: type: string description: HTTP method you can use to retrieve the resource. example: get signature: type: object description: "Polymorphic object that contains information about how we captured the owner's signature. \n\nThe value of the type parameter determines which variant you should use:\n-\t`requestedViaDirectLink` - Request signature using a link.\n-\t`requestedViaEmail` - Request signature by email.\n" discriminator: *ref_293 oneOf: *ref_294 metadata: type: object additionalProperties: type: string description: Object that you can send to include custom metadata in the request. example: customerId: '2345' links: readOnly: true type: array description: Array of useful links related to your request. items: type: object readOnly: true description: Object that contains HATEOAS links for the resource. properties: *ref_4 required: *ref_5 example: *ref_6 examples: created: summary: Created merchant platform description: New merchant platform created value: &ref_1006 merchantPlatformId: '12345' createdDate: '2024-07-02T12:00:00.000Z' lastModifiedDate: '2024-07-02T12:00:00.000Z' business: name: Example Corp taxId: xxxxx6789 organizationType: privateCorporation countryOfOperation: US addresses: - type: legalAddress address1: 1 Example Ave. address2: Example Address Line 2 address3: Example Address Line 3 city: Chicago state: Illinois country: US postalCode: '60056' contactMethods: - type: email value: jane.doe@example.com processingAccounts: - processingAccountId: '38765' doingBusinessAs: Pizza Doe status: pending link: rel: processingAccount href: https://api.payroc.com/v1/processing-accounts/38765 method: get signature: type: requestedViaDirectLink link: rel: agreement href: https://us.agreementexpress.net/mv2/viewer2.jsp?docId=00000000-0000-0000-0000-000000000000 method: get partialSuccess: summary: Failed processing account description: We successfully created the merchant platform, but failed to add one or more processing accounts. value: &ref_1007 merchantPlatformId: '12346' createdDate: '2024-07-02T12:00:00.000Z' lastModifiedDate: '2024-07-02T12:00:00.000Z' business: name: Example Corp taxId: xxxxx6789 organizationType: privateCorporation countryOfOperation: US addresses: - type: legalAddress address1: 1 Example Ave. address2: Example Address Line 2 address3: Example Address Line 3 city: Chicago state: Illinois country: US postalCode: '60056' contactMethods: - type: email value: jane.doe@example.com - type: phone value: 555 555 3456 processingAccounts: - doingBusinessAs: Pizza Doe status: failed headers: location: description: URI reference to the resource. schema: type: string '400': description: Validation error. content: application/problem+json: schema: type: object properties: *ref_9 required: *ref_10 examples: validationError: summary: Bad Request description: One or more validation errors occurred value: *ref_11 idempotentKeyMissing: summary: Idempotency key missing description: Idempotency key must be supplied value: *ref_26 fundingAccountsLimitReached: summary: Funding accounts limit reached description: Funding accounts restricted. You can not have any more than two funding accounts attached to this entity value: &ref_307 type: https://docs.payroc.com/api/errors#funding-accounts-limit-reached title: Funding accounts limit reached status: 400 detail: You can not have any more than two funding accounts attached to this entity tooManyControlProngs: summary: Too many control prongs description: Your request included more than one owner as the control prong. You can set only one owner as the control prong. value: &ref_308 type: https://docs.payroc.com/api/errors#too-many-control-prongs title: Too many control prongs status: 400 detail: You can set only one owner as the control prong noControlProng: summary: No control prong or authorized signatory description: Your request didn’t indicate which owner is the control prong or the authorized signatory. Set one owner as the control prong or the authorized signatory. value: &ref_309 type: https://docs.payroc.com/api/errors#no-control-prong-or-authorized-signatory title: No control prong or authorized signatory status: 400 detail: Set one owner as the control prong or the authorized signatory dailyDiscountAndRewardPayConflict: summary: Cannot select Daily Discount and RewardPayChoice at the same time. description: You can't select Daily Discount with a RewardPayChoice pricing plan. To select Daily Discount, choose a different pricing plan. value: &ref_310 type: https://docs.payroc.com/api/errors#daily-discount-and-reward-pay-conflict title: Cannot select Daily Discount and RewardPayChoice at the same time. status: 400 detail: Choose a different pricing plan or don't select Daily Discount. '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '406': description: Not acceptable content: *ref_19 '409': description: Conflict content: application/problem+json: schema: type: object properties: *ref_27 required: *ref_28 examples: idempotentKeyInUse: summary: Idempotency key in use description: Idempotency key in use value: *ref_29 taxIdInUse: summary: Tax ID in use description: The tax ID supplied is already in use. value: &ref_1008 type: https://docs.payroc.com/api/errors#tax-id-in-use title: Tax ID already in use status: 409 detail: The tax ID that you supplied is already in use. Supply a unique tax ID nationalIdInUse: summary: National ID in use description: One or more supplied national IDs are not unique. All national IDs must be unique. value: &ref_1009 type: https://docs.payroc.com/api/errors#national-id-in-use title: National ID in use status: 409 detail: One or more supplied national IDs are not unique. All national IDs must be unique '500': description: An error has occured content: *ref_14 get: tags: - Merchant platforms summary: List merchant platforms description: | Use this method to return a [paginated](https://docs.payroc.com/api/pagination) list of merchant platforms that are linked to your ISV account. **Note**: If you want to view the details of a specific merchant platform and you have its merchantPlatformId, use our [Retrieve Merchant Platform](https://docs.payroc.com/api/schema/boarding/merchant-platforms/retrieve) method. Our gateway returns the following information about each merchant platform in the list: - Legal information, including its legal name and address. - Contact information, including the email address for the business. - Processing account information, including the processingAccountId and status of each processing account that's linked to the merchant platform. For each merchant platform, we also return its merchantPlatformId and its linked processingAccountIds, which you can use to perform follow-on actions. operationId: listMerchantPlatforms parameters: - name: before in: query description: | Return the previous page of results before the value that you specify. You can’t send the before parameter in the same request as the after parameter. schema: *ref_32 examples: *ref_33 - name: after in: query description: | Return the next page of results after the value that you specify. You can’t send the after parameter in the same request as the before parameter. schema: *ref_34 examples: *ref_35 - name: limit in: query description: Limit the maximum number of results that we return for each page. schema: *ref_36 examples: *ref_37 responses: '200': description: Successful request. Returns a list of merchant platforms associated with the ISV's account. content: application/json: schema: type: object title: paginated merchant platforms allOf: &ref_805 - type: object description: Contains the pagination properties that you use to navigate through a list of results. properties: *ref_38 - type: object properties: data: type: array description: Array of merchantPlatform objects. items: type: object title: merchant required: *ref_295 properties: *ref_296 examples: listMerchantPlatforms: summary: Paginated list of merchant platforms description: Retrieve a list of merchant platforms associated with your account. value: &ref_1004 limit: 2 count: 2 hasMore: true links: - rel: previous method: get href: https://api.payroc.com/v1/merchant-platforms?before=12345&limit=2 - rel: next method: get href: https://api.payroc.com/v1/merchant-platforms?after=12346&limit=2 data: - merchantPlatformId: '12345' createdDate: '2024-07-02T12:00:00.000Z' lastModifiedDate: '2024-07-02T12:00:00.000Z' business: name: Example Corp taxId: xxxxx6789 organizationType: privateCorporation countryOfOperation: US addresses: - type: legalAddress address1: 1 Example Ave. address2: Example Address Line 2 address3: Example Address Line 3 city: Chicago state: Illinois country: US postalCode: '60056' contactMethods: - type: email value: example-corp@example.com - type: phone value: 123 456 7890 processingAccounts: - processingAccountId: '38765' doingBusinessAs: Pizza Doe status: pending link: rel: processingAccount href: https://api.payroc.com/v1/processing-accounts/38765 method: get signature: type: requestedViaDirectLink link: rel: agreement href: https://us.agreementexpress.net/mv2/viewer2.jsp?docId=00000000-0000-0000-0000-000000000000 method: get - merchantPlatformId: '12346' createdDate: '2024-07-02T12:00:00.000Z' lastModifiedDate: '2024-07-02T12:00:00.000Z' business: name: Example Corp taxId: xxxxx6789 organizationType: privateCorporation countryOfOperation: US addresses: - type: legalAddress address1: 1 Example Ave. address2: Example Address Line 2 address3: Example Address Line 3 city: Chicago state: Illinois country: US postalCode: '60056' contactMethods: - type: email value: example-corp@example.com - type: phone value: 123 456 7890 processingAccounts: - processingAccountId: '38766' doingBusinessAs: Doe Hot Dogs status: pending link: rel: processingAccount href: https://api.payroc.com/v1/processing-accounts/38766 method: get signature: type: requestedViaDirectLink link: rel: agreement href: https://us.agreementexpress.net/mv2/viewer2.jsp?docId=00000000-0000-0000-0000-000000000001 method: get noActivity: summary: No records found description: Valid request, but no records match the criteria. value: *ref_55 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '406': description: Not acceptable content: *ref_19 '500': description: An error has occured content: *ref_14 /merchant-platforms/{merchantPlatformId}: get: tags: - Merchant platforms summary: Retrieve merchant platform description: "Use this method to retrieve information about a merchant platform. \n\nTo retrieve a merchant platform, you need its merchantPlatformId. Our gateway returned the merchantPlatformId in the response of the [Create Merchant Platform](https://docs.payroc.com/api/schema/boarding/merchant-platforms/create) method. \n\n**Note:** If you don't have the merchantPlatformId, use our [List Merchant Platforms](https://docs.payroc.com/api/schema/boarding/merchant-platforms/list) method to search for the merchant platform.\n\nOur gateway returns the following information about the merchant platform:\n-\tLegal information, including its legal name and address.\n-\tContact information, including the email address for the business. \n-\tProcessing account information, including the processingAccountId and status of each processing account that's linked to the merchant platform. \n" operationId: getMerchantAccounts parameters: - name: merchantPlatformId in: path description: Unique identifier of the merchant platform that we sent to you when you created the merchant platform. required: true schema: &ref_297 type: string examples: &ref_298 example: value: '12345' responses: '200': description: Successful request. Returns the merchant platform. content: application/json: schema: type: object title: merchant required: *ref_295 properties: *ref_296 examples: retrievedMerchantPlatforms: summary: Retrieve merchant platform description: Retrieve a merchant platform. value: &ref_1010 merchantPlatformId: '12345' createdDate: '2024-07-02T12:00:00.000Z' lastModifiedDate: '2024-07-02T12:00:00.000Z' business: name: Example Corp taxId: xxxxx6789 organizationType: privateCorporation countryOfOperation: US addresses: - type: legalAddress address1: 1 Example Ave. address2: Example Address Line 2 address3: Example Address Line 3 city: Chicago state: Illinois country: US postalCode: '60056' contactMethods: - type: email value: jane.doe@example.com processingAccounts: - processingAccountId: '38765' doingBusinessAs: Pizza Doe status: approved link: rel: processingAccount href: https://api.payroc.com/v1/processing-accounts/38765 method: get signature: type: requestedViaDirectLink link: rel: agreement href: https://us.agreementexpress.net/mv2/viewer2.jsp?docId=00000000-0000-0000-0000-000000000000 method: get metadata: customerId: '2345' links: [] '400': description: Invalid request content: *ref_15 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '404': description: Resource not found content: *ref_18 '406': description: Not acceptable content: *ref_19 '500': description: An error has occured content: *ref_14 /merchant-platforms/{merchantPlatformId}/processing-accounts: get: tags: - Merchant platforms summary: List merchant platform's processing accounts description: | Use this method to return a [paginated](https://docs.payroc.com/api/pagination) list of processing accounts linked to a merchant platform. **Note**: If you want to view the details of a specific processing account and you have its processingAccountId, use our [Retrieve Processing Account](https://docs.payroc.com/api/schema/boarding/processing-accounts/retrieve) method. Use the query parameters to filter the list of results that we return, for example, to search for only closed processing accounts. To list the processing accounts for a merchant platform, you need its merchantPlatformId. If you don't have the merchantPlatformId, use our [List Merchant Platforms](https://docs.payroc.com/api/schema/boarding/merchant-platforms/list) method to search for the merchant platform. Our gateway returns the following information about eahc processing account in the list: - Business details, including its status, time zone, and address. - Owners' details, including their contact details. - Funding, pricing, and processing information, including its pricing model and funding accounts. For each processing account, we also return its processingAccountId, which you can use to perform follow-on actions. operationId: listMerchantLocations parameters: - name: merchantPlatformId in: path description: Unique identifier of the merchant platform that we sent to you when you created the merchant platform. required: true schema: *ref_297 examples: *ref_298 - name: before in: query description: | Return the previous page of results before the value that you specify. You can’t send the before parameter in the same request as the after parameter. schema: *ref_32 examples: *ref_33 - name: after in: query description: | Return the next page of results after the value that you specify. You can’t send the after parameter in the same request as the before parameter. schema: *ref_34 examples: *ref_35 - name: limit in: query description: Limit the maximum number of results that we return for each page. schema: *ref_36 examples: *ref_37 - name: includeClosed in: query description: | Indicates if you want to return closed processing accounts. This includes processing accounts that have a status of `terminated`, `cancelled`, or `rejected`. **Note**: By default, we return only open processing accounts. schema: &ref_513 type: boolean default: false examples: &ref_514 example: value: false responses: '200': description: Successful request. Returns a list of processing accounts associated with the merchant platform. content: application/json: schema: type: object title: paginated processing accounts allOf: &ref_816 - type: object description: Contains the pagination properties that you use to navigate through a list of results. properties: *ref_38 - type: object properties: data: type: array description: Array of processingAccount objects. items: required: &ref_305 - doingBusinessAs - owners - businessType - merchandiseOrServiceSold - timezone - address - contactMethods - processing - funding - pricing - signature - categoryCode type: object properties: &ref_306 processingAccountId: type: string readOnly: true description: Unique identifier of the processing account. example: '38765' createdDate: type: string format: date-time readOnly: true description: Date and time that we received your request to create the processing account in our system. example: '2024-07-02T12:00:00.000Z' lastModifiedDate: type: string format: date-time readOnly: true description: Date and time that the processing account was last modified. example: '2024-07-02T12:00:00.000Z' status: type: string description: | Status of the processing account. - `entered` - We have received information about the account, but we have not yet reviewed it. - `pending` - We have reviewed the information about the account, but we have not yet approved it. - `approved` - We have approved the account for processing transactions and funding. - `subjectTo` - We have approved the account, but we are waiting on further information. - `dormant` - Account is closed for a period. - `nonProcessing` - We have approved the account, but the merchant has not yet run a transaction. - `rejected` - We rejected the application for the processing account. - `terminated` - Processing account is closed. - `cancelled` - Merchant withdrew the application for the processing account. **Note**: You can subscribe to our processingAccount.status.changed event to get notifications when we change the status of a processing account. For more information about how to subscribe to events, go to [Event Subscriptions](https://docs.payroc.com/guides/board-merchants/event-subscriptions). readOnly: true enum: - entered - pending - approved - subjectTo - dormant - nonProcessing - rejected - terminated - cancelled example: entered doingBusinessAs: type: string description: Trading name of the business. maxLength: 100 example: Pizza Doe owners: readOnly: true description: Object that contains information about the owners of the business. type: array items: type: object title: owner properties: ownerId: description: Unique identifier of the owner. type: integer example: 4564 firstName: description: Owner's first name. type: string example: Jane lastName: description: Owner's last name. type: string example: Doe link: description: HATEOAS links to the owners of the processing account. type: object properties: rel: type: string description: Indicates the relationship between the current resource and the target resource. example: owner href: type: string description: URL of the target resource. example: https://api.payroc.com/v1/owners/1543 method: type: string description: HTTP method that you need to use with the target resource. example: get website: type: string description: Website address of the business. maxLength: 128 example: www.example.com businessType: type: string description: Type of business. enum: - retail - restaurant - internet - moto - lodging - notForProfit example: restaurant categoryCode: type: integer format: int32 example: 5999 description: Merchant Category Code (MCC) for the type of business. maxLength: 4 merchandiseOrServiceSold: type: string description: Description of the services or merchandise sold by the business. maxLength: 125 example: Pizza businessStartDate: type: string format: date description: Date that the business was established. The format of the value is **YYYY-MM-DD**. example: '2020-01-01' timezone: description: Time zone for the processing account. enum: *ref_299 example: America/Chicago maxLength: 28 address: type: object description: Polymorphic object that contains address information for the processing account. oneOf: - required: *ref_0 type: object title: address description: Object that contains information about the address. properties: *ref_1 contactMethods: type: array minItems: 1 description: "Array of polymorphic objects, which contain contact information. \n\n**Note:** You must provide an email address.\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" items: discriminator: *ref_2 oneOf: *ref_3 processing: description: Object that contains information about how we process transactions for the account. type: object title: processing required: *ref_300 properties: *ref_301 funding: type: object description: Object that contains funding information for the processing account, including funding schedules, funding fees, and details of funding accounts. allOf: &ref_815 - type: object properties: *ref_302 - type: object properties: fundingAccounts: description: Object that contains funding accounts associated with the processing account. minItems: 1 maxItems: 2 readOnly: true type: array items: type: object title: funding account summary properties: &ref_814 fundingAccountId: description: Unique identifier that we assigned to the funding account. type: integer readOnly: true example: 123 status: description: Status of the funding account. type: string readOnly: true example: pending enum: - approved - rejected - pending link: description: Object that contains HATEOAS links for the funding accounts that are linked to the processing account. readOnly: true type: object properties: *ref_4 required: *ref_5 example: *ref_6 pricing: type: object description: Object that HATEOAS links to the pricing information that we apply to the processing account. properties: link: type: object description: Object that contains HATEOAS links to the pricing information for the processing account. properties: rel: type: string example: pricing description: Indicates the relationship between the current resource and the target resource. href: type: string example: https://api.payroc.com/v1/processing-accounts/38765/pricing description: URL of the target resource. method: type: string example: get description: HTTP method that you need to use with the target resource. contacts: readOnly: true description: Array of contact objects. type: array items: type: object title: contact properties: contactId: type: integer description: Unique identifier of the contact. example: 1543 firstName: type: string description: Contact's first name. example: Jane lastName: type: string description: Contact's last name. example: Doe link: type: object description: Object that contains HATEOAS links for the contact. properties: rel: type: string example: contact description: Relationship to the parent resource. href: type: string example: https://api.payroc.com/v1/contacts/1543 description: Link to the resource. method: type: string example: get description: HTTP method you can use to retrieve the resource. signature: type: object description: "Polymorphic object that contains information about how we captured the owner's signature. \n\nThe value of the type parameter determines which variant you should use:\n-\t`requestedViaDirectLink` - Request signature using a link.\n-\t`requestedViaEmail` - Request signature by email.\n" discriminator: *ref_293 oneOf: *ref_294 metadata: type: object additionalProperties: type: string description: Object that you can send to include custom data in the request. For more information about how to use metadata, go to [Metadata](https://docs.payroc.com/api/metadata). example: customerId: '2345' links: type: array description: Array of useful links related to your request. items: type: object readOnly: true description: Object that contains HATEOAS links for the resource. properties: *ref_4 required: *ref_5 example: *ref_6 example: [] examples: listProcessingAccounts: summary: Paginated list of processing account description: Retrieve processing accounts associated with a merchant platform. value: &ref_1011 limit: 2 count: 2 hasMore: true links: - rel: previous method: get href: https://api.payroc.com/v1/merchant-platforms/12345/processing-accounts?before=38765&limit=2 - rel: next method: get href: https://api.payroc.com/v1/merchant-platforms/12345/processing-accounts?after=38766&limit=2 data: - processingAccountId: '38765' createdDate: '2024-07-02T12:00:00.000Z' lastModifiedDate: '2024-07-02T12:00:00.000Z' status: approved doingBusinessAs: Pizza Doe owners: - ownerId: 4564 firstName: Jane lastName: Doe link: rel: owner href: https://api.payroc.com/v1/owners/4564 method: get website: www.example.com businessType: restaurant categoryCode: 5999 merchandiseOrServiceSold: Food businessStartDate: '2020-01-01' timezone: America/Chicago address: address1: 1 Example Ave. address2: Example Address Line 2 address3: Example Address Line 3 city: Chicago state: Illinois country: US postalCode: '60056' contactMethods: - type: email value: example-corp@example.com - type: phone value: 123 456 7890 processing: merchantId: '444412365478965' transactionAmounts: average: 1000 highest: 200000 monthlyAmounts: average: 1000000 highest: 200000000 volumeBreakdown: cardPresent: 77 mailOrTelephone: 3 ecommerce: 20 isSeasonal: true monthsOfOperation: - jan - feb - mar - nov - dec ach: naics: '5812' previouslyTerminatedForAch: false refunds: writtenRefundPolicy: true refundPolicyUrl: http://www.example.com/refunds estimatedMonthlyTransactions: 1000 limits: singleTransaction: 10000000 dailyDeposit: 1000 monthlyDeposit: 2000 transactionTypes: - telephoneInitiatedPayment - webInitiatedPayment cardAcceptance: debitOnly: false hsaFsa: false cardsAccepted: - visa - mastercard specialityCards: americanExpressDirect: enabled: true merchantNumber: '1234567890' electronicBenefitsTransfer: enabled: true fnsNumber: '1234567' other: wexMerchantNumber: '1234567890' voyagerMerchantId: '1234567890' fleetMerchantId: '1234567890' funding: status: enabled fundingSchedule: nextday acceleratedFundingFee: 1999 fundingAccounts: - fundingAccountId: 123 status: pending link: rel: fundingAccount method: get href: https://api.payroc.com/v1/funding-accounts/123 pricing: link: rel: pricing method: get href: https://api.payroc.com/v1/processing-accounts/12345/pricing signature: type: requestedViaEmail contacts: - contactId: 1543 firstName: Jane lastName: Doe link: rel: owner href: https://api.payroc.com/v1/contacts/1543 method: get - processingAccountId: '38766' createdDate: '2024-07-02T12:00:00.000Z' lastModifiedDate: '2024-07-02T12:00:00.000Z' status: approved doingBusinessAs: Doe Hot Dogs owners: - ownerId: 4564 firstName: Jane lastName: Doe link: rel: owner href: https://api.payroc.com/v1/owners/4564 method: get website: www.example.com businessType: internet categoryCode: 5999 merchandiseOrServiceSold: Food businessStartDate: '2020-01-01' timezone: America/Chicago address: address1: 3 Example Ave. address2: Example Address Line 2 address3: Example Address Line 3 city: Chicago state: Illinois country: US postalCode: '60056' contactMethods: - type: email value: jane.doe@example.com - type: phone value: 555 555 3456 processing: merchantId: '444412365478966' transactionAmounts: average: 2000 highest: 300000 monthlyAmounts: average: 2000000 highest: 300000000 volumeBreakdown: cardPresent: 0 mailOrTelephone: 0 ecommerce: 100 isSeasonal: true funding: status: enabled fundingSchedule: nextday acceleratedFundingFee: 1999 fundingAccounts: - fundingAccountId: 124 status: pending link: rel: fundingAccount method: get href: https://api.payroc.com/v1/funding-accounts/124 pricing: link: rel: pricing method: get href: https://api.payroc.com/v1/processing-accounts/12346/pricing signature: type: requestedViaEmail contacts: - contactId: 1543 firstName: Jane lastName: Doe link: rel: owner href: https://api.payroc.com/v1/contacts/1543 method: get noActivity: summary: No records found description: Valid request, but no records match the criteria. value: *ref_55 '400': description: Invalid request content: *ref_15 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '406': description: Not acceptable content: *ref_19 '500': description: An error has occured content: *ref_14 post: tags: - Merchant platforms summary: Create processing account description: | Use this method to add an additional processing account to a merchant platform. To add a processing account to a merchant platform, you need the merchantPlatformId. Our gateway returned the merchantPlatformId in the response of the [Create Merchant Platform](https://docs.payroc.com/api/schema/boarding/merchant-platforms/create) method. **Note**: If you don't have the merchantPlatformId, use our [List Merchant Platforms](https://docs.payroc.com/api/schema/boarding/merchant-platforms/list) method to search for the merchant platform. In the request, include the following information: - Business details, including its business type, time zone, and address. - Owners' details, including their contact details. - Funding, pricing, and processing information, including its pricing model and funding accounts. When you send a successful request, we review the information about the processing account. After we complete our review and approve the processing account, we assign a processingAccountId, which you need to perform follow-on actions. **Note**: You can subscribe to our processingAccount.status.changed event to get notifications when we update the status of a processing account. For more information about how to subscribe to events, go to [Events List](https://docs.payroc.com/knowledge/events/events-list). operationId: createProcessingAccount parameters: - name: merchantPlatformId in: path description: Unique identifier of the merchant platform that we sent to you when you created the merchant platform. required: true schema: *ref_297 examples: *ref_298 - name: Idempotency-Key in: header required: true 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). schema: *ref_22 examples: *ref_23 requestBody: content: application/json: schema: required: *ref_303 type: object properties: *ref_304 examples: retrievedMerchantPlatforms: summary: Create merchant platform description: Create a merchant platform. value: &ref_1012 doingBusinessAs: Pizza Doe owners: - firstName: Jane middleName: Helen lastName: Doe dateOfBirth: '1964-03-22' address: address1: 1 Example Ave. address2: Example Address Line 2 address3: Example Address Line 3 city: Chicago state: Illinois country: US postalCode: '60056' identifiers: - type: nationalId value: 000-00-4320 contactMethods: - type: email value: jane.doe@example.com relationship: equityPercentage: 51.5 title: CFO isControlProng: true isAuthorizedSignatory: false website: www.example.com businessType: restaurant categoryCode: 5999 merchandiseOrServiceSold: Pizza businessStartDate: '2020-01-01' timezone: America/Chicago address: address1: 1 Example Ave. address2: Example Address Line 2 address3: Example Address Line 3 city: Chicago state: Illinois country: US postalCode: '60056' contactMethods: - type: email value: jane.doe@example.com processing: transactionAmounts: average: 5000 highest: 10000 monthlyAmounts: average: 50000 highest: 100000 volumeBreakdown: cardPresent: 77 mailOrTelephone: 3 ecommerce: 20 isSeasonal: true monthsOfOperation: - jan - feb ach: naics: '5812' previouslyTerminatedForAch: false refunds: writtenRefundPolicy: true refundPolicyUrl: www.example.com/refund-poilcy-url estimatedMonthlyTransactions: 3000 limits: singleTransaction: 10000 dailyDeposit: 200000 monthlyDeposit: 6000000 transactionTypes: - prearrangedPayment - other transactionTypesOther: anotherTransactionType cardAcceptance: debitOnly: false hsaFsa: false cardsAccepted: - visa - mastercard specialityCards: americanExpressDirect: enabled: true merchantNumber: abc1234567 electronicBenefitsTransfer: enabled: true fnsNumber: '6789012' other: wexMerchantNumber: abc1234567 voyagerMerchantId: abc1234567 fleetMerchantId: abc1234567 funding: fundingSchedule: nextday acceleratedFundingFee: 1999 dailyDiscount: false fundingAccounts: - type: checking use: creditAndDebit nameOnAccount: Jane Doe paymentMethods: - type: ach value: routingNumber: '123456789' accountNumber: '1234567890' metadata: yourCustomField: abc123 pricing: type: intent pricingIntentId: '6123' signature: type: requestedViaDirectLink contacts: - type: manager firstName: Jane middleName: Helen lastName: Doe identifiers: - type: nationalId value: 000-00-4320 contactMethods: - type: email value: jane.doe@example.com metadata: customerId: '2345' responses: '201': description: Successful request. We created the processing account. content: application/json: schema: required: *ref_305 type: object properties: *ref_306 examples: retrievedMerchantPlatforms: summary: Retrieve merchant platform description: Retrieve a merchant platform. value: &ref_1013 processingAccountId: '38765' createdDate: '2024-07-02T12:00:00.000Z' lastModifiedDate: '2024-07-02T12:00:00.000Z' status: entered doingBusinessAs: Pizza Doe owners: - ownerId: 4564 firstName: Jane lastName: Doe link: rel: owner href: https://api.payroc.com/v1/owners/4564 method: get website: www.example.com businessType: restaurant categoryCode: 5999 merchandiseOrServiceSold: Pizza businessStartDate: '2020-01-01' timezone: America/Chicago address: address1: 1 Example Ave. address2: Example Address Line 2 address3: Example Address Line 3 city: Chicago state: Illinois country: US postalCode: '60056' contactMethods: - type: email value: jane.doe@example.com processing: transactionAmounts: average: 5000 highest: 10000 monthlyAmounts: average: 50000 highest: 100000 volumeBreakdown: cardPresent: 77 mailOrTelephone: 3 ecommerce: 20 isSeasonal: true monthsOfOperation: - jan - feb ach: naics: '5812' previouslyTerminatedForAch: false refunds: writtenRefundPolicy: true refundPolicyUrl: www.example.com/refund-poilcy-url estimatedMonthlyTransactions: 3000 limits: singleTransaction: 10000 dailyDeposit: 200000 monthlyDeposit: 6000000 transactionTypes: - prearrangedPayment - other transactionTypesOther: anotherTransactionType cardAcceptance: debitOnly: false hsaFsa: false cardsAccepted: - visa - mastercard specialityCards: americanExpressDirect: enabled: true merchantNumber: abc1234567 electronicBenefitsTransfer: enabled: true fnsNumber: '6789012' other: wexMerchantNumber: abc1234567 voyagerMerchantId: abc1234567 fleetMerchantId: abc1234567 funding: status: enabled fundingSchedule: nextday acceleratedFundingFee: 1999 dailyDiscount: false fundingAccounts: - fundingAccountId: 123 status: pending link: rel: fundingAccount method: get href: https://api.payroc.com/v1/funding-accounts/123 pricing: link: rel: pricing href: https://api.payroc.com/v1/processing-accounts/12345/pricing method: get contacts: - contactId: 1543 firstName: Jane lastName: Doe link: rel: contact href: https://api.payroc.com/v1/contacts/1543 method: get signature: type: requestedViaDirectLink link: rel: agreement href: https://us.agreementexpress.net/mv2/viewer2.jsp?docId=00000000-0000-0000-0000-000000000000 method: get metadata: customerId: '2345' headers: location: description: URI reference to the resource. schema: type: string '400': description: Validation error. content: application/problem+json: schema: type: object properties: *ref_9 required: *ref_10 examples: validationError: summary: Bad Request description: One or more validation errors occurred value: *ref_11 idempotentKeyMissing: summary: Idempotency key missing description: Idempotency key must be supplied value: *ref_26 fundingAccountsLimitReached: summary: Funding accounts limit reached description: Funding accounts restricted. You can not have any more than two funding accounts attached to this entity value: *ref_307 tooManyControlProngs: summary: Too many control prongs description: Your request included more than one owner as the control prong. You can set only one owner as the control prong. value: *ref_308 noControlProng: summary: No control prong or authorized signatory description: Your request didn’t indicate which owner is the control prong or the authorized signatory. Set one owner as the control prong or the authorized signatory. value: *ref_309 dailyDiscountAndRewardPayConflict: summary: Cannot select Daily Discount and RewardPayChoice at the same time. description: You can't select Daily Discount with a RewardPayChoice pricing plan. To select Daily Discount, choose a different pricing plan. value: *ref_310 '401': description: Identity could not be verified content: *ref_12 '404': description: Resource not found content: *ref_18 '406': description: Not acceptable content: *ref_19 '409': description: Conflict content: application/problem+json: schema: type: object properties: *ref_27 required: *ref_28 examples: idempotentKeyInUse: summary: Idempotency key in use description: Idempotency key in use value: *ref_29 '500': description: An error has occured content: *ref_14 /processing-accounts/{processingAccountId}: get: tags: - Processing accounts summary: Retrieve processing account description: "Use this method to retrieve information about a specific processing account. \n\nTo retrieve a processing account, you need its processingAccountId. Our gateway returned the processingAccountId in the response of the [Create Merchant Platform](https://docs.payroc.com/api/schema/boarding/merchant-platforms/create) method or the [Create Processing Account](https://docs.payroc.com/api/schema/boarding/merchant-platforms/create-processing-account) method. \n\n**Note:** If you don't have the processingAccountId, use our [List Merchant Platform's Processing Accounts](https://docs.payroc.com/api/schema/boarding/merchant-platforms/list-processing-accounts) method to search for the processing account. \n\nOur gateway returns the following information about the processing account: \n\n-\tBusiness information, including the Merchant Category Code (MCC), status of the processing account, and address of the business. \n-\tProcessing information, including the merchant’s refund policies and card types that the merchant accepts. \n-\tFunding information, including funding schedules, funding fees, and details for the merchant’s funding accounts. \n-\tPricing information, including [HATEOAS](https://docs.payroc.com/knowledge/basic-concepts/hypermedia-as-the-engine-of-application-state-hateoas) links to retrieve the pricing program for the processing account. \n" operationId: getProcessingAccounts parameters: - name: processingAccountId in: path description: Unique identifier that we assigned to the processing account. required: true schema: &ref_311 type: string examples: &ref_312 example: value: '38765' responses: '200': description: Successful request. Returns the processing account. content: application/json: schema: required: *ref_305 type: object properties: *ref_306 examples: processingAccount: summary: Retrieve processing account description: Retrieve a specific processing account. value: &ref_1014 processingAccountId: '38765' createdDate: '2024-07-02T12:00:00.000Z' lastModifiedDate: '2024-07-02T12:00:00.000Z' status: approved doingBusinessAs: Pizza Doe owners: - ownerId: 4564 firstName: Jane lastName: Doe link: rel: owner href: https://api.payroc.com/v1/owners/1543 method: get website: www.example.com businessType: restaurant categoryCode: 5999 merchandiseOrServiceSold: Pizza businessStartDate: '2020-01-01' timezone: America/Chicago address: address1: 1 Example Ave. address2: Example Address Line 2 address3: Example Address Line 3 city: Chicago state: Illinois country: US postalCode: '60056' contactMethods: - type: email value: jane.doe@example.com processing: merchantId: '444412365478965' transactionAmounts: average: 5000 highest: 10000 monthlyAmounts: average: 50000 highest: 100000 volumeBreakdown: cardPresent: 77 mailOrTelephone: 3 ecommerce: 20 isSeasonal: true monthsOfOperation: - jan - feb ach: naics: '5812' previouslyTerminatedForAch: false refunds: writtenRefundPolicy: true refundPolicyUrl: www.example.com/refund-poilcy-url estimatedMonthlyTransactions: 3000 limits: singleTransaction: 10000 dailyDeposit: 200000 monthlyDeposit: 6000000 transactionTypes: - prearrangedPayment - other transactionTypesOther: anotherTransactionType cardAcceptance: debitOnly: false hsaFsa: false cardsAccepted: - visa - mastercard specialityCards: americanExpressDirect: enabled: true merchantNumber: abc1234567 electronicBenefitsTransfer: enabled: true fnsNumber: '6789012' other: wexMerchantNumber: abc1234567 voyagerMerchantId: abc1234567 fleetMerchantId: abc1234567 funding: status: enabled fundingSchedule: nextday acceleratedFundingFee: 1999 dailyDiscount: false fundingAccounts: - fundingAccountId: 123 status: pending link: rel: fundingAccount method: get href: https://api.payroc.com/v1/funding-accounts/123 pricing: link: rel: pricing href: https://api.payroc.com/v1/processing-accounts/38765/pricing method: get contacts: - contactId: 1543 firstName: Jane lastName: Doe link: rel: contact href: https://api.payroc.com/v1/contacts/1543 method: get signature: type: requestedViaDirectLink link: rel: agreement href: https://us.agreementexpress.net/mv2/viewer2.jsp?docId=00000000-0000-0000-0000-000000000000 method: get metadata: customerId: '2345' '400': description: Invalid request content: *ref_15 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '404': description: Resource not found content: *ref_18 '406': description: Not acceptable content: *ref_19 '500': description: An error has occured content: *ref_14 /processing-accounts/{processingAccountId}/funding-accounts: get: tags: - Processing accounts summary: List processing account's funding accounts description: | Use this method to return a list of funding accounts linked to a processing acccount. To retrieve a list of funding accounts for a processing account, you need the processingAccountId. Our gateway returned the processingAccountId in the response of the [Create Merchant Platform](https://docs.payroc.com/api/schema/boarding/merchant-platforms/create) method or the [Create Proccessing Account](https://docs.payroc.com/api/schema/boarding/merchant-platforms/create-processing-account) method. Our gateway returns information about the following for each funding account in the list: - Account information, including the name on the account and payment methods. - Status, including whether we have approved or rejected the account. For each funding account, we also return its fundingAccountId, which you can use to perform follow-on actions. operationId: listProcessingAccountsFundingAccounts parameters: - name: processingAccountId in: path description: Unique identifier that we assigned to the processing account. required: true schema: *ref_311 examples: *ref_312 responses: '200': description: Successful request. Returns a list of funding accounts associated with the processing account. content: application/json: schema: type: array description: | Array of funding account objects for the processing account. Each processing account must have: - One funding account that accepts both credits to the account and debits from the account. OR - Two funding accounts - one for credits to the account, and another account for debits from the account. items: required: *ref_20 type: object title: funding account properties: *ref_21 examples: fundingAccounts: summary: List of funding accounts description: List of funding accounts associated with a processing account. value: &ref_1015 - fundingAccountId: 123 createdDate: '2024-07-02T12:00:00.000Z' lastModifiedDate: '2024-07-02T12:00:00.000Z' status: approved type: checking use: creditAndDebit nameOnAccount: Jane Doe paymentMethods: - type: ach value: routingNumber: '*****6789' accountNumber: '******7890' metadata: yourCustomField: abc123 links: - rel: parent href: https://api.payroc.com/v1/processing-accounts/38765 method: get - fundingAccountId: 124 createdDate: '2024-07-02T12:00:00.000Z' lastModifiedDate: '2024-07-02T12:00:00.000Z' status: pending type: checking use: creditAndDebit nameOnAccount: Jane Doe paymentMethods: - type: ach value: routingNumber: '*****8725' accountNumber: '******3491' metadata: yourCustomField: abc123 links: - rel: parent href: https://api.payroc.com/v1/processing-accounts/38765 method: get '400': description: Invalid request content: *ref_15 '401': description: Identity could not be verified content: *ref_12 '403': description: Identity could not be verified content: *ref_12 '404': description: Resource not found content: *ref_18 '406': description: Not acceptable content: *ref_19 '500': description: An error has occured content: *ref_14 /processing-accounts/{processingAccountId}/contacts: get: tags: - Processing accounts summary: List contacts description: | Use this method to return a list of contacts for a processing account. **Note:** If you want to view the details of a specific contact and you have their contactId, use our [Retrieve Contact](https://docs.payroc.com/api/schema/boarding/contacts/retrieve) method. To list contacts for a processing account, you need the processingAccountId. Our gateway returned the processingAccountId in the response of the [Create Merchant Platform](https://docs.payroc.com/api/schema/boarding/merchant-platforms/create) method or the [Create Processing Account](https://docs.payroc.com/api/schema/boarding/merchant-platforms/create-processing-account) method. Our gateway returns the following information about each contact: - Name and contact method, including their phone number or mobile number. - Role within the business, for example, if they are a manager. For each contact, we also return a contactId, which you can use to perform follow-on actions. operationId: listProcessingAccountContacts parameters: - name: processingAccountId in: path description: Unique identifier that we assigned to the processing account. required: true schema: *ref_311 examples: *ref_312 - name: before in: query description: | Return the previous page of results before the value that you specify. You can’t send the before parameter in the same request as the after parameter. schema: *ref_32 examples: *ref_33 - name: after in: query description: | Return the next page of results after the value that you specify. You can’t send the after parameter in the same request as the before parameter. schema: *ref_34 examples: *ref_35 - name: limit in: query description: Limit the maximum number of results that we return for each page. schema: *ref_36 examples: *ref_37 responses: '200': description: Successful request. Returns a list of contacts associated with the processing account. content: application/json: schema: type: object title: paginated Contacts allOf: &ref_817 - type: object description: Contains the pagination properties that you use to navigate through a list of results. properties: *ref_38 - type: object properties: data: type: array description: Array of contact objects. items: type: object title: contact required: *ref_313 properties: *ref_314 examples: paginatedContacts: summary: Paginated list of processing account contacts description: List of contacts associated with a processing account. value: &ref_1016 limit: 2 count: 2 hasMore: true links: - rel: previous method: get href: https://api.payroc.com/v1/processing-accounts/38765/contacts?before=1543&limit=2 - rel: next method: get href: https://api.payroc.com/v1/processing-accounts/38765/contacts?after=87926&limit=2 data: - contactId: 1543 type: manager firstName: Jane middleName: Helen lastName: Doe identifiers: - type: nationalId value: xxxxx4320 contactMethods: - type: phone value: '2025550164' - type: mobile value: '8445557624' - type: email value: jane.doe@example.com - contactId: 87926 type: representative firstName: Fred middleName: Jim lastName: Nerk identifiers: - type: nationalId value: xxxxx9876 contactMethods: - type: phone value: '2025550110' - type: mobile value: '85655587451' - type: email value: fred.nerk@example.com noActivity: summary: No records found description: Valid request, but no records match the criteria. value: *ref_55 '400': description: Invalid request content: *ref_15 '401': description: Identity could not be verified content: *ref_12 '403': description: Identity could not be verified content: *ref_12 '406': description: Not acceptable content: *ref_19 '500': description: An error has occured content: *ref_14 /processing-accounts/{processingAccountId}/pricing: get: summary: Retrieve processing account pricing agreement description: | Use this method to retrieve the pricing agreement that we apply to a processing account. To retrieve the pricing agreement of a processing account, you need the processingAccountId. Our gateway returned the processingAccountId in the response to the [Create Merchant Platform](https://docs.payroc.com/api/schema/boarding/merchant-platforms/create) method and [Create Processing Account](https://docs.payroc.com/api/schema/boarding/merchant-platforms/create-processing-account) method. **Note:** If you don't have the processingAccountId, use our [List Merchant Platform’s Processing Accounts](https://docs.payroc.com/api/schema/boarding/merchant-platforms/list-processing-accounts) method to search for the processing account. Our gateway returns the following information about the pricing agreement that we apply to the processing account: - Base fees, including the annual fee and the fees for each chargeback and retrieval. - Processor fees, including the fees that we apply for processing card and ACH payments. - Gateway fees, including the setup fee and the fees for each transaction. - Service fees, including the fee that we apply if the merchant has signed up to a Hardware Advantage Plan. operationId: retrieveProcessingAccountPricing tags: - Processing accounts parameters: - name: processingAccountId in: path description: Unique identifier that we assigned to the processing account. required: true schema: *ref_311 examples: *ref_312 responses: '200': description: "Successful request. We return a polymorphic object that contains the pricing agreement for the processing account. \n\nThe value of the version field determines which variant you should use: \n-\t`4.0` - Pricing agreement version 4.\n-\t`5.0` - Pricing agreement version 5.\n" content: application/json: schema: oneOf: - type: object title: US pricing agreement version 4.0 description: Object that contains information about U.S. pricing intents for Merchant Processing Agreement (MPA) 4.0. required: &ref_828 - country - version - base properties: &ref_829 country: type: string description: Two-digit code for the country that the pricing intent applies to. The format follows the [ISO-3166-1](https://www.iso.org/iso-3166-country-codes.html) standard. enum: - US version: type: string description: Version of the MPA. enum: - '4.0' base: type: object title: US base fees description: Object that contains information about U.S. base fees. properties: *ref_315 required: *ref_316 processor: type: object title: US processor fees description: Object that contains information about U.S. processor fees. properties: card: type: object description: "Polymorphic object that contains fees for card transactions. \n\nThe value of the planType field determines which variant you should use: \n-\t`interchangePlus` - Interchange + pricing\n-\t`interchangePlusTiered3` - Interchange pricing with three tiers\n-\t`tiered3` - Three-tiered pricing \n-\t`tiered4` - Four-tiered pricing\n-\t`tiered6` - Six-tiered pricing\n-\t`flatRate` - Flat rate pricing\n-\t`consumerChoice` - ConsumerChoice \n-\t`rewardPay` - RewardPay\n-\t`rewardPayChoice` - RewardPayChoice\n" discriminator: propertyName: planType mapping: interchangePlus: '#/components/schemas/interchangePlus' interchangePlusTiered3: '#/components/schemas/interchangePlusTiered3' tiered3: '#/components/schemas/tiered3' tiered4: '#/components/schemas/tiered4' tiered6: '#/components/schemas/tiered6' flatRate: '#/components/schemas/flatRate' consumerChoice: '#/components/schemas/consumerChoice' rewardPay: '#/components/schemas/rewardPay' rewardPayChoice: '#/components/schemas/rewardPayChoice' oneOf: - type: object title: Interchange Plus Plan description: Object that contains information about Interchange Plus. properties: *ref_317 required: *ref_318 - type: object title: Interchange Plus with three tiers description: Object that contains information about Interchange Plus with three tiers. properties: &ref_822 planType: type: string description: Type of processing plan. enum: - interchangePlusTiered3 fees: type: object description: Object that contains information about the fees. properties: mastercardVisaDiscover: description: Object that contains the fees for Mastercard, Visa, and Discover transactions. type: object required: *ref_52 properties: *ref_53 amex: description: "Polymorphic object that contains fees for American Express transactions. \n\nThe value of the type field determines which variant you should use: \n-\t`optBlue` - Amex OptBlue pricing program.\n-\t`direct` - Amex Direct pricing program.\n" discriminator: propertyName: type mapping: optBlue: '#/components/schemas/interchangePlusTiered3AmexOptBlue' direct: '#/components/schemas/interchangePlusTiered3AmexDirect' oneOf: - type: object title: optBlue required: &ref_818 - type - qualifiedRate - midQualRate - nonQualRate properties: &ref_819 type: type: string description: Type of American Express program. enum: - optBlue qualifiedRate: description: Object that contains the fees for a qualified transaction. type: object title: Processor Fee properties: *ref_43 midQualRate: description: Object that contains the fees for a mid-qualified transaction. type: object title: Processor Fee properties: *ref_43 nonQualRate: description: Object that contains the fees for a non-qualified transaction. type: object title: Processor Fee properties: *ref_43 - type: object title: direct required: &ref_820 - type - transaction properties: &ref_821 type: type: string description: Type of American Express program. enum: - direct transaction: description: Fee for each transaction. The value is in the currency's lowest denomination, for example, cents. allOf: - type: integer minimum: 0 pinDebit: type: object description: Object that contains the fees for PIN-debit transactions. required: *ref_44 properties: *ref_45 electronicBenefitsTransfer: type: object description: Object that contains the fees for EBT transactions. required: *ref_46 properties: *ref_47 enhancedInterchange: type: object description: Object that contains the fees for enhanced interchange services. required: *ref_48 properties: *ref_49 specialityCards: type: object description: Object that contains the fees for speciality cards. required: *ref_50 properties: *ref_51 required: - mastercardVisaDiscover required: &ref_823 - planType - fees - type: object title: Tiered pricing with three tiers description: Object that contains information about tiered pricing with three tiers. properties: *ref_319 required: *ref_320 - type: object title: Tiered pricing with four tiers description: Object that contains information about tiered pricing with four tiers. properties: *ref_321 required: *ref_322 - type: object title: Tiered pricing with six tiers description: Object that contains information about tiered pricing with six tiers. properties: *ref_323 required: *ref_324 - type: object title: Flat Rate Plan description: Object that contains information about Flat Rate. properties: *ref_325 required: *ref_326 - type: object title: Consumer Choice Plan description: Object that contains information about ConsumerChoice. properties: *ref_327 required: *ref_328 - type: object title: RewardPay Plan description: Object that contains information about RewardPay. properties: &ref_824 planType: description: Type of processing plan. type: string enum: - rewardPay fees: type: object description: Object that contains information about the fees. properties: monthlySubscription: description: Fee for the monthly subscription for the processing plan. The value is in the currency's lowest denomination, for example, cents. allOf: - type: integer minimum: 0 cardChargePercentage: description: Percentage of the total transaction amount that the processor charges the cardholder. type: number readOnly: true default: 3 allOf: - description: Percentage value up to 2 decimal places. title: percentage type: number format: double minimum: 0 maximum: 100 example: 1.25 merchantChargePercentage: description: Percentage of the total transaction amount that the processor charges the merchant. type: number readOnly: true default: 0.9 allOf: - description: Percentage value up to 2 decimal places. title: percentage type: number format: double minimum: 0 maximum: 100 example: 1.25 transaction: description: Fee for each transaction. The value is in the currency's lowest denomination, for example, cents. type: integer readOnly: true default: 15 tips: description: Indicates how the merchant manages tips. type: string enum: - noTips - tipPrompt - tipAdjust specialityCards: type: object description: Object that contains the fees for speciality cards. required: *ref_50 properties: *ref_51 required: - monthlySubscription - tips required: &ref_825 - planType - fees - type: object title: RewardPayChoice Plan description: Object that contains information about RewardPayChoice. properties: *ref_329 required: *ref_330 ach: type: object description: Object that contains the fees for ACH transactions. properties: *ref_331 gateway: type: object description: Object that contains information about the gateway fees. title: gateway fees properties: &ref_826 fees: type: object description: Object that contains information about the gateway fees. properties: monthly: description: Monthly fee for the gateway. The value is in the currency's lowest denomination, for example, cents. allOf: - type: integer minimum: 0 setup: description: Fee for setting up your account with the gateway. The value is in the currency's lowest denomination, for example, cents. allOf: - type: integer minimum: 0 perTransaction: description: Fee for each transaction. The value is in the currency's lowest denomination, for example, cents. allOf: - type: integer minimum: 0 perDeviceMonthly: description: Monthly fee for each device. The value is in the currency's lowest denomination, for example, cents. allOf: - type: integer minimum: 0 additionalServiceMonthly: description: Monthly fee for additional service. The value is in the currency's lowest denomination, for example, cents. allOf: - type: integer minimum: 0 required: - monthly - setup - perTransaction - perDeviceMonthly - additionalServiceMonthly required: &ref_827 - fees - type: object title: US pricing agreement version 5.0 description: Object that contains information about U.S. pricing intents for Merchant Processing Agreement (MPA) 5.0. required: *ref_287 properties: *ref_288 examples: paginatedContacts: summary: Get processing account pricing agreement description: Retrieve a pricing agreement for a processing account. value: &ref_1017 country: US version: '5.0' base: addressVerification: 5 annualFee: billInMonth: december amount: 9900 regulatoryAssistanceProgram: 15 pciNonCompliance: 4995 merchantAdvantage: 10 platinumSecurity: billingFrequency: monthly amount: 1295 maintenance: 500 minimum: 100 voiceAuthorization: 95 chargeback: 2500 retrieval: 1500 batch: 5 earlyTermination: 57500 processor: card: planType: interchangePlus fees: mastercardVisaDiscover: volume: 1.25 transaction: 0 amex: type: optBlue volume: 1.25 transaction: 0 pinDebit: additionalDiscount: 1.25 transaction: 0 monthlyAccess: 0 electronicBenefitsTransfer: transaction: 0 enhancedInterchange: enrollment: 0 creditToMerchant: 1.25 specialityCards: transaction: 0 ach: fees: transaction: 50 batch: 1000 returns: 400 unauthorizedReturn: 1999 statement: 800 monthlyMinimum: 20000 accountVerification: 100 discountRateUnder10000: 1.25 discountRateAbove10000: 1.25 gateway: fees: monthly: 0 setup: 0 perTransaction: 0 perDeviceMonthly: 0 '400': description: Invalid request content: *ref_15 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '404': description: Resource not found content: *ref_18 '406': description: Not acceptable content: *ref_19 '500': description: An error has occured content: *ref_14 /processing-accounts/{processingAccountId}/owners: get: tags: - Processing accounts summary: List owners description: | Use this method to return a list of owners of a processing account. **Note:** If you want to view the details of a specific owner and you have the ownerId, go to our [Retrieve Owner](https://docs.payroc.com/api/schema/boarding/owners/retrieve) method. To list the owners of a processing account, you need its processingAccountId. If you don't have the processingAccountId, use our [List Merchant Platform's Processing Accounts](https://docs.payroc.com/api/schema/boarding/merchant-platforms/list-processing-accounts) method to search for the processing account. Our gateway returns the following information about each owner in the list: - Name, date of birth, and address. - Contact details, including their email address. - Relationship to the business, including whether they are a control prong or authorized signatory, and their equity stake in the business. operationId: listMerchantOwners parameters: - name: processingAccountId in: path description: Unique identifier that we assigned to the processing account. required: true schema: *ref_311 examples: *ref_312 - name: before in: query description: | Return the previous page of results before the value that you specify. You can’t send the before parameter in the same request as the after parameter. schema: *ref_32 examples: *ref_33 - name: after in: query description: | Return the next page of results after the value that you specify. You can’t send the after parameter in the same request as the before parameter. schema: *ref_34 examples: *ref_35 - name: limit in: query description: Limit the maximum number of results that we return for each page. schema: *ref_36 examples: *ref_37 responses: '200': description: Successful request. Returns a list of owners associated with the processing account. content: application/json: schema: type: object title: paginated Owners allOf: &ref_830 - type: object description: Contains the pagination properties that you use to navigate through a list of results. properties: *ref_38 - type: object properties: data: type: array description: Array of owner objects. items: type: object title: owner required: *ref_30 properties: *ref_31 examples: listProcessingAccountOwners: summary: Paginated list of processing account owners description: Retrieve owners associated with a processing account. value: &ref_1018 limit: 2 count: 2 hasMore: true links: - rel: previous method: get href: https://api.payroc.com/v1/processing-accounts/38765/owners?before=4564&limit=2 - rel: next method: get href: https://api.payroc.com/v1/processing-accounts/38765/owners?after=12346&limit=2 data: - ownerId: 4564 firstName: Jane middleName: Helen lastName: Doe dateOfBirth: '1964-03-22' address: address1: 1 Example Ave. address2: Example Address Line 2 address3: Example Address Line 3 city: Chicago state: Illinois country: US postalCode: '60056' identifiers: - type: nationalId value: xxxxx4320 contactMethods: - type: email value: jane.doe@example.com - type: phone value: '2025550164' relationship: equityPercentage: 48.5 title: CFO isControlProng: true isAuthorizedSignatory: false - ownerId: 12346 firstName: Fred middleName: Jim lastName: Nerk dateOfBirth: '1980-01-19' address: address1: 2 Example Ave. address2: Example Address Line 2 address3: Example Address Line 3 city: Chicago state: Illinois country: US postalCode: '60056' identifiers: - type: nationalId value: xxxxx9876 contactMethods: - type: email value: fred.nerk@example.com relationship: equityPercentage: 51.5 title: CEO isControlProng: false isAuthorizedSignatory: true noActivity: summary: No records found description: Valid request, but no records match the criteria. value: *ref_55 '400': description: Invalid request content: *ref_15 '401': description: Identity could not be verified content: *ref_12 '404': description: Resource not found content: *ref_18 '406': description: Not acceptable content: *ref_19 '500': description: An error has occured content: *ref_14 /processing-accounts/{processingAccountId}/reminders: post: tags: - Processing accounts summary: Create reminder for processing account description: | Use this method to prompt a merchant to sign their pricing agreement. You can create a reminder only if you requested the merchant’s signature by email when you created the processing account for the merchant. To create a reminder, you need the processingAccountId. Our gateway returned the processingAccountId in the response of the [Create Merchant Platform](https://docs.payroc.com/api/schema/boarding/merchant-platforms/create) method or [Create Processing Account](https://docs.payroc.com/api/schema/boarding/merchant-platforms/create-processing-account) method. **Note:** If you don’t know the processingAccountId, use our [List Merchant Platform’s Processing Accounts](https://docs.payroc.com/api/schema/boarding/merchant-platforms/list-processing-accounts) method to search for the processing account. When you send a successful request, we send an email to the merchant that prompts them to sign their pricing agreement. operationId: createReminder parameters: - name: Idempotency-Key in: header required: true 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). schema: *ref_22 examples: *ref_23 - name: processingAccountId in: path description: Unique identifier that we assigned to the processing account. required: true schema: *ref_311 examples: *ref_312 requestBody: description: Polymorphic object that contains reminder details. content: application/json: schema: discriminator: propertyName: type mapping: pricingAgreement: '#/components/schemas/pricingAgreementReminder' oneOf: - description: Object that contains information about the pricing agreement reminder. type: object required: &ref_332 - type properties: &ref_333 reminderId: type: string description: Unique ID of the reminder. readOnly: true example: '1234567' type: type: string description: Type of reminder. enum: - pricingAgreement example: pricingAgreement examples: createReminderForProcessingAccount: summary: Create reminder for processing account description: | When you create a processing account, we send a copy of the pricing agreement to the merchant to sign. You can choose to send them a copy of the pricing agreement by email, or you can generate a link to the pricing agreement.
If you requested the merchant's signature by email and they don't respond, use our Reminders endpoint to create a reminder and to send another email.
**Note:** You can use the Reminders endpoint only if you request the merchant's signature by email. If you generate a link to the pricing agreement, you can't use the Reminders endpoint. value: &ref_1019 type: pricingAgreement responses: '201': description: Successful request. We sent an email to the merchant and we return a polymorphic object that contains reminder details. content: application/json: schema: discriminator: propertyName: type mapping: pricingAgreement: '#/components/schemas/pricingAgreementReminder' oneOf: - description: Object that contains information about the pricing agreement reminder. type: object required: *ref_332 properties: *ref_333 examples: reminderCreated: summary: Reminder created description: Reminder created. value: &ref_1020 reminderId: '1234567' type: pricingAgreement '400': description: Bad request content: application/problem+json: schema: type: object properties: *ref_9 required: *ref_10 examples: badRequest: summary: Bad Request description: One or more validation errors occurred value: *ref_11 notRequestedByEmail: summary: Not requested by email description: We couldn't resend the email to the merchant because you didn't originally choose to send the information by email. value: &ref_1021 type: https://docs.payroc.com/api/errors#not-requested-by-email title: Not requested by email status: 400 detail: You can use the Reminders endpoint only for documentation that we sent by email. contractAlreadySigned: summary: Contract already signed description: We couldn’t resend the email because the merchant already signed the contract. value: &ref_1022 type: https://docs.payroc.com/api/errors#contract-already-signed title: Contract already signed status: 400 detail: The merchant has already signed the contract. noPricingAgreementExistsForTheProcessingAccount: summary: No pricing agreement exists for the processing account description: We couldn’t resend the email because there is no pricing agreement for the processing account. value: &ref_1023 type: https://docs.payroc.com/api/errors#no-pricing-agreement-exists-for-the-processing-account title: No pricing agreement exists status: 400 detail: There is no pricing agreement linked to the processing account. idempotentKeyMissing: summary: Idempotency key missing description: Idempotency key must be supplied value: *ref_26 '403': description: Do not have permissions to perform this action content: *ref_13 '404': description: Resource not found content: *ref_18 '409': description: Conflict content: application/problem+json: schema: type: object properties: *ref_27 required: *ref_28 examples: idempotentKeyInUse: summary: Idempotency key in use description: Idempotency key in use value: *ref_29 '500': description: An error has occured content: *ref_14 /processing-accounts/{processingAccountId}/terminal-orders: post: summary: Create terminal order description: | Use this method to order and configure terminals for a processing account. **Note**: You need the ID of the processing account before you can create an order. If you don't know the processingAccountId, go to the [Retrieve a Merchant Platform](https://docs.payroc.com/api/schema/boarding/merchant-platforms/retrieve) method. In the request, specify the gateway settings, device settings, and application settings for the terminal. In the response, our gateway returns information about the terminal order including its status and terminalOrderId that you can use to [retrieve the terminal order](https://docs.payroc.com/api/schema/boarding/terminal-orders/retrieve). **Note**: You can subscribe to the terminalOrder.status.changed event to get notifications when we update the status of a terminal order. For more information about how to subscribe to events, go to [Events Subscriptions](https://docs.payroc.com/guides/board-merchants/event-subscriptions). operationId: createTerminalOrder tags: - Processing accounts parameters: - name: Idempotency-Key in: header required: true 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). schema: *ref_22 examples: *ref_23 - name: processingAccountId in: path description: Unique identifier that we assigned to the processing account. required: true schema: *ref_311 examples: *ref_312 requestBody: content: application/json: schema: type: object properties: &ref_841 trainingProvider: type: string description: Indicates who provides training to the merchant for the solution. enum: &ref_334 - partner - payroc maxLength: 7 default: partner shipping: type: object description: Object that contains the shipping details for the terminal order. If you don't provide a shipping address, we use the Doing Business As (DBA) address of the processing account. properties: &ref_335 preferences: type: object description: Object that contains the shipping preferences for the terminal order. properties: method: type: string description: | Shipping method for the terminal order. Send one of the following values: - `nextDay` - We schedule the order to be delivered the next day. - `ground` - We ship the order with ground shipping. enum: - nextDay - ground default: nextDay saturdayDelivery: type: boolean description: Indicates if we can schedule the terminal order to be delivered on a Saturday. default: false address: type: object description: Object that contains the shipping address for the terminal order. properties: recipientName: type: string description: Name of the person receiving the shipment. maxLength: 100 businessName: type: string description: Name of the business receiving the shipment. maxLength: 100 addressLine1: type: string description: First line of the shipment address. maxLength: 100 addressLine2: type: string description: Second line of the shipment address. maxLength: 100 city: type: string description: City of the shipment address. maxLength: 50 state: type: string description: State of the shipment address. maxLength: 30 postalCode: type: string description: Postal code of the shipment address. maxLength: 9 email: type: string description: Contact email address for the shipment. format: email maxLength: 100 phone: type: string description: Contact number for the shipment. maxLength: 15 required: - recipientName - addressLine1 - city - state - postalCode - email orderItems: type: array description: Array of order items. Provide a minimum of 1 order item and a maximum of 10 order items. items: type: object properties: &ref_336 type: type: string description: Type of item. enum: - solution maxLength: 8 solutionTemplateId: type: string description: | Unique identifier of the solution. Send one of the following values: - `Roc Services_DX8000` - `Roc Services_DX4000` - `Roc Services_Web` - `Roc Services_Mobile` - `Payroc DX8000` - `Payroc DX4000` - `Payroc RX7000_Cloud` - `Payroc DX8000_Cloud` - `Payroc DX4000_Cloud` - `Payroc A920Pro` - `Payroc A80` - `Payroc A920Pro_Cloud` - `Payroc A80_Cloud` - `Roc Terminal Plus_N950` - `Roc Terminal Plus_N950-S` - `Roc Terminal Plus_X800` - `Gateway_Payroc` - `VAR_Only_TSYS` - `ROC Services Chipper3X` - `BBPOS Chipper 3X` - `Augusta EMV` - `Ingenico - AXIUM Full Functional Base` - `Pax A920 Charging Base` - `Pax A920 Comms Base` - `A920 Pro Ethernet` - `Axium Bundle` maxLength: 100 solutionQuantity: type: number description: Quantity of the solution. format: integer default: 1 maximum: 50 deviceCondition: type: string description: Indicates if the order contains a new item or a refurbished item. enum: - new - refurbished maxLength: 11 solutionSetup: type: object description: Object that contains the settings for the solution, including gateway settings, device settings, and application settings. properties: timezone: type: string description: | Time zone of the terminal. **Note**: If you don't send a value for this parameter, we use the time zone of the processing account. enum: &ref_831 - Pacific/Midway - Pacific/Honolulu - America/Anchorage - America/Los_Angeles - America/Denver - America/Phoenix - America/Chicago - America/Indiana/Indianapolis - America/New_York example: America/Chicago maxLength: 28 industryTemplateId: type: string description: | Unique identifier of the industry template you want to apply to the solution. Send one of the following values: - `Retail` - `Restaurant` - `Moto` - `Ecommerce` maxLength: 100 gatewaySettings: type: object description: Object that contains the gateway settings for the solution. properties: merchantPortfolioId: type: string description: Unique identifier of the merchant portfolio. maxLength: 100 merchantTemplateId: type: string description: Unique identifier of the gateway merchant template. maxLength: 100 userTemplateId: type: string description: Unique identifier of the gateway user template. maxLength: 100 terminalTemplateId: type: string description: Unique identifier of the gateway terminal template. maxLength: 100 applicationSettings: type: object description: Object that contains the application settings for the solution. properties: clerkPrompt: type: boolean description: Indicates if the terminal should prompt the clerk, for example, if the terminal should prompt when the clerk needs to enter an amount on the terminal. example: true security: type: object description: Object that contains the password settings when running specific transaction types. properties: refundPassword: type: boolean description: Indicates if the terminal should prompt the clerk for a password when running a refund. keyedSalePassword: type: boolean description: Indicates if the terminal should prompt the clerk for a password when running a keyed sale. reversalPassword: type: boolean description: Indicates if the terminal should prompt the clerk for a password when cancelling a transaction. deviceSettings: type: object description: Object that contains the device settings if the solution includes a terminal or a peripheral device such as a printer. properties: numberOfMobileUsers: type: number format: integer description: Number of users that we need to set up for mobile solutions. communicationType: type: string description: Method of connection between a terminal or a peripheral device and the host. enum: - bluetooth - cellular - ethernet - wifi maxLength: 9 batchClosure: description: Object that contains information about when and how the terminal closes the batch. discriminator: propertyName: batchCloseType mapping: automatic: '#/components/schemas/automaticBatchClose' manual: '#/components/schemas/manualBatchClose' oneOf: - type: object title: automatic description: Indicates how the merchant batches their transactions. properties: &ref_832 batchCloseType: type: string description: | Indicates how the merchant batches their transactions. Send one of the following: - `automatic` - Terminal automatically closes the batch each day. To set the time the batch closes, send a value for the batchCloseTime parameter. - `manual` - Merchant manually closes their batch. enum: - automatic batchCloseTime: type: string description: Time that the batch automatically closes. example: '23:40' maxLength: 5 required: &ref_833 - batchCloseType - type: object title: manual description: Indicates how the merchant batches their transactions. properties: &ref_834 batchCloseType: type: string description: | Indicates how the merchant batches their transactions. Send one of the following: - `automatic` - Terminal automatically closes the batch each day. To set the time the batch closes, send a value for the batchCloseTime parameter. - `manual` - Merchant manually closes their batch. enum: - manual required: &ref_835 - batchCloseType receiptNotifications: type: object description: Object that indicates if the terminal can send email receipts, text receipts, or both. properties: emailReceipt: description: Indicates if the terminal can send receipts by email. type: boolean smsReceipt: description: Indicates if the terminal can send receipts by text message. type: boolean taxes: type: array description: Array of tax objects that contains the taxes that apply to the merchant's transactions. items: type: object description: Tax that applies to the merchant's transactions. properties: taxRate: description: Rate of tax that the terminal applies to each transaction. type: number format: decimal minimum: 0 maximum: 99.999 taxLabel: type: string description: Short description of the tax rate, for example, "Sales Tax". maxLength: 10 required: - taxRate - taxLabel maxItems: 3 minItems: 0 tips: type: object description: Object that contains the tip options for transactions ran on the terminal. properties: enabled: type: boolean description: Indicates if the terminal can accept tips. tokenization: type: boolean description: Indicates if the terminal can tokenize customer's payment details. For more information about tokenization, go to [Tokenization.](https://docs.payroc.com/knowledge/basic-concepts/tokenization) example: true required: &ref_337 - type - solutionTemplateId minItems: 1 maxItems: 20 required: &ref_842 - orderItems examples: terminalOrder: summary: Terminal order description: | Use this method to order and configure terminals for a processing account. When you create an order, you specify the gateway settings, device settings, and application settings for the terminals. **Note**: You need the ID of the merchant's processing account before you can create an order. If you don't know the processingAccountId, go to [Retrieve a Merchant Platform.](#getMerchantAccounts) value: &ref_1025 trainingProvider: payroc shipping: preferences: method: nextDay saturdayDelivery: true address: recipientName: Recipient Name businessName: Company Ltd addressLine1: 1 Example Ave. addressLine2: Example Address Line 2 city: Chicago state: Illinois postalCode: '60056' email: example@mail.com phone: '2025550164' orderItems: - type: solution solutionTemplateId: Roc Services_DX8000 solutionQuantity: 1 deviceCondition: new solutionSetup: timezone: America/Chicago industryTemplateId: Retail gatewaySettings: merchantPortfolioId: Company Ltd merchantTemplateId: Company Ltd Merchant Template userTemplateId: Company Ltd User Template terminalTemplateId: Company Ltd Terminal Template applicationSettings: clerkPrompt: false security: refundPassword: true keyedSalePassword: false reversalPassword: true deviceSettings: numberOfMobileUsers: 2 communicationType: wifi batchClosure: batchCloseType: automatic batchCloseTime: '23:40' receiptNotifications: emailReceipt: true smsReceipt: false taxes: - taxRate: 6 taxLabel: Sales Tax tips: enabled: false tokenization: true responses: '201': description: Successful request. We created the terminal order. content: application/json: schema: type: object properties: &ref_341 terminalOrderId: type: string description: Unique identifier that we assigned to the terminal order. example: '12345' status: type: string description: | Status of the terminal order. **Note**: You can subscribe to our terminalOrder.status.changed event to get notifications when we update the status of a terminal order. For more information about how to subscribe to events, go to [Event Subscriptions](https://docs.payroc.com/guides/board-merchants/event-subscriptions). enum: - open - held - dispatched - fulfilled - cancelled example: open trainingProvider: &ref_839 type: string description: Indicates who provides training to the merchant for the solution. enum: *ref_334 maxLength: 7 default: partner shipping: &ref_840 type: object description: Object that contains the shipping details for the terminal order. If you don't provide a shipping address, we use the Doing Business As (DBA) address of the processing account. properties: *ref_335 orderItems: type: array description: Array of orderItem objects. Provide a minimum of 1 order item and a maximum of 20 order items. items: type: object allOf: - type: object properties: *ref_336 required: *ref_337 - type: object description: Array of links related to your order items. properties: &ref_838 links: type: array description: Polymorphic object that contains information about the processing terminal that the order is linked to. items: type: object anyOf: - type: object description: Object that contains information about the processing terminal. properties: &ref_836 processingTerminalId: type: string description: Unique identifier that we assigned to the processing terminal. link: required: - href - rel - method type: object properties: href: type: string description: URL of the target resource. 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. description: Array of links related to your request. For more information about HATEOAS, go to [Hypermedia as the engine of application state](https://docs.payroc.com/knowledge/basic-concepts/hypermedia-as-the-engine-of-application-state-hateoas). required: &ref_837 - processingTerminalId - link minItems: 1 maxItems: 20 createdDate: type: string format: date-time readOnly: true description: Date that we received the terminal order. We return this value in the [ISO-8601](https://www.iso.org/iso-8601-date-and-time-format.html) format. example: '2020-09-08T12:00:00.000Z' lastModifiedDate: type: string format: date-time readOnly: true description: Date that the terminal order was last changed. We return this value in the [ISO-8601](https://www.iso.org/iso-8601-date-and-time-format.html) format. example: '2020-09-09T12:00:00.000Z' required: &ref_342 - terminalOrderId - status - orderItems - createdDate - lastModifiedDate examples: terminalOrder: summary: Terminal order description: Terminal order value: &ref_1026 terminalOrderId: '12345' status: open trainingProvider: payroc shipping: preferences: method: nextDay saturdayDelivery: true address: recipientName: Recipient Name businessName: Company Ltd addressLine1: 1 Example Ave. addressLine2: Example Address Line 2 city: Chicago state: Illinois postalCode: '60056' email: example@mail.com phone: '2025550164' orderItems: - type: solution solutionTemplateId: Roc Services_DX8000 solutionQuantity: 1 deviceCondition: new solutionSetup: timezone: America/Chicago industryTemplateId: Retail gatewaySettings: merchantPortfolioId: Company Ltd merchantTemplateId: Company Ltd Merchant Template userTemplateId: Company Ltd User Template terminalTemplateId: Company Ltd Terminal Template applicationSettings: clerkPrompt: false security: refundPassword: true keyedSalePassword: false reversalPassword: true deviceSettings: numberOfMobileUsers: 2 communicationType: wifi batchClosure: batchCloseType: automatic batchCloseTime: '23:40' receiptNotifications: emailReceipt: true smsReceipt: false taxes: - taxRate: 6 taxLabel: Sales Tax tips: enabled: false tokenization: true createdDate: '2024-07-02T12:00:00.000Z' lastModifiedDate: '2024-07-02T12:00:00.000Z' '400': description: Bad request content: application/problem+json: schema: type: object properties: *ref_9 required: *ref_10 examples: validationError: summary: Bad Request description: One or more validation errors occurred value: *ref_11 idempotentKeyMissing: summary: Idempotency key missing description: Idempotency key must be supplied value: *ref_26 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '404': description: Not found content: application/problem+json: schema: type: object properties: *ref_338 required: *ref_339 examples: notFound: summary: Not found description: Resource could not be found value: *ref_340 '409': description: Conflict content: application/problem+json: schema: type: object properties: *ref_27 required: *ref_28 examples: idempotentKeyInUse: summary: Idempotency key in use description: Idempotency key in use value: *ref_29 '500': description: An error has occured content: *ref_14 get: summary: List terminal orders description: | Use this method to return a [paginated](https://docs.payroc.com/api/pagination) list of terminal orders associated with a processing account. **Note:** If you want to view the details of a specific terminal order and you have its terminalOrderId, use our [Retrieve Terminal Order](https://docs.payroc.com/api/schema/boarding/terminal-orders/retrieve) method. Use the query parameters to filter the list of results that we return, for example, to search for terminal orders by their status. To list the terminal orders for a processing account, you need its processingAccountId. If you don't have the processingAccountId, use our [List Merchant Platforms](https://docs.payroc.com/api/schema/boarding/merchant-platforms/list) method to search for a merchant platform and its processing accounts. Our gateway returns the following information for each terminal order in the list: - Status of the order - Items in the order - Training provider - Shipping information For each terminal order, we also return its terminalOrderId, which you can use to perform follow-on actions. operationId: listProcessingAccountsTerminalOrders tags: - Processing accounts parameters: - name: processingAccountId in: path description: Unique identifier that we assigned to the processing account. required: true schema: *ref_311 examples: *ref_312 - name: status in: query schema: &ref_515 type: string description: Filter terminal orders by status. enum: - open - held - dispatched - fulfilled - cancelled - name: fromDateTime in: query schema: &ref_516 type: string format: date-time description: Filter by terminal orders created after a specific date. The date format follows the [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) standard. example: '2024-09-08T12:00:00.000Z' - name: toDateTime in: query schema: &ref_517 type: string format: date-time description: Filter by terminal orders created before a specific date. The date format follows the [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html). example: '2024-12-08T11:00:00.000Z' responses: '200': description: Successful request. Returns a list of terminal orders associated with the processing account. content: application/json: schema: type: array description: Array of terminal order objects. items: type: object properties: *ref_341 required: *ref_342 examples: terminalOrders: summary: Paginated list of Terminal Orders description: Retrieve terminal orders associated with a processing account. value: &ref_1024 - terminalOrderId: '12345' status: open trainingProvider: payroc shipping: preferences: method: nextDay saturdayDelivery: true address: recipientName: Recipient Name businessName: Company Ltd addressLine1: 1 Example Ave. addressLine2: Example Address Line 2 city: Chicago state: Illinois postalCode: '60056' email: example@mail.com phone: '2025550164' orderItems: - type: solution solutionTemplateId: Roc Services_DX8000 solutionQuantity: 1 deviceCondition: new solutionSetup: timezone: America/Chicago industryTemplateId: Retail gatewaySettings: merchantPortfolioId: Company Ltd merchantTemplateId: Company Ltd Merchant Template userTemplateId: Company Ltd User Template terminalTemplateId: Company Ltd Terminal Template applicationSettings: clerkPrompt: false security: refundPassword: true keyedSalePassword: false reversalPassword: true deviceSettings: numberOfMobileUsers: 2 communicationType: wifi batchClosure: batchCloseType: automatic batchCloseTime: '23:40' receiptNotifications: emailReceipt: true smsReceipt: false taxes: - taxRate: 6 taxLabel: Sales Tax tips: enabled: false tokenization: true links: - processingTerminalId: '1234001' link: rel: processingTerminal method: get href: https://api.payroc.com/v1/processing-terminals/1234001 createdDate: '2024-07-02T12:00:00.000Z' lastModifiedDate: '2024-07-02T12:00:00.000Z' '400': description: Invalid request content: *ref_15 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '404': description: Resource not found content: *ref_18 '406': description: Not acceptable content: *ref_19 '500': description: An error has occured content: *ref_14 /processing-accounts/{processingAccountId}/processing-terminals: get: summary: List processing terminals description: | Use this method to return a [paginated](https://docs.payroc.com/api/pagination) list of processing terminals associated with a processing account. **Note:** If you want to view the details of a specific processing terminal and you have its processingTerminalId, use our [Retrieve Processing Terminal](https://docs.payroc.com/api/schema/boarding/processing-terminals/retrieve) method. To list the terminals for a processing account, you need its processingAccountId. If you don't have the processingAccountId, use our [List Merchant Platforms](https://docs.payroc.com/api/schema/boarding/merchant-platforms/list) method to search for a merchant platform and its processing accounts. Our gateway returns the following information for each processing terminal in the list: - Status indicating whether the terminal is active or inactive. - Configuration settings, including gateway settings and application settings. - Features, receipt settings, and security settings. - Devices that use the processing terminal's configuration. For each processing terminal, we also return its processingTerminalId, which you can use to perform follow-on actions. operationId: listProcessingAccountsProcessingTerminals tags: - Processing accounts parameters: - name: processingAccountId in: path description: Unique identifier that we assigned to the processing account. required: true schema: *ref_311 examples: *ref_312 - name: before in: query description: | Return the previous page of results before the value that you specify. You can’t send the before parameter in the same request as the after parameter. schema: *ref_32 examples: *ref_33 - name: after in: query description: | Return the next page of results after the value that you specify. You can’t send the after parameter in the same request as the before parameter. schema: *ref_34 examples: *ref_35 - name: limit in: query description: Limit the maximum number of results that we return for each page. schema: *ref_36 examples: *ref_37 responses: '200': description: Successful request. Returns a list of processing terminals associated with the processing account. content: application/json: schema: type: object title: paginated Processing Terminals allOf: &ref_858 - type: object description: Contains the pagination properties that you use to navigate through a list of results. properties: *ref_38 - type: object properties: data: type: array description: Array of processing terminal objects. items: type: object properties: &ref_344 processingTerminalId: type: string description: Unique identifier that we assigned to the processing terminal. example: '011234001' status: type: string description: Indicates if the processing terminal is active. enum: - active - inactive maxLength: 8 timezone: type: string description: Time zone of the processing terminal. maxLength: 28 enum: - Pacific/Midway - Pacific/Honolulu - America/Anchorage - America/Los_Angeles - America/Denver - America/Phoenix - America/Chicago - America/Indiana/Indianapolis - America/New_York example: America/Chicago program: type: string description: Name of the product and its setup. maxLength: 50 gateway: description: Polymorphic object that contains the gateway settings for the solution. discriminator: propertyName: gateway mapping: payroc: '#/components/schemas/payrocGateway' anyOf: - type: object description: Object that contains the gateway settings for the solution. properties: &ref_843 gateway: type: string description: Name of the gateway that processes the transactions. enum: - payroc terminalTemplateId: type: string description: Unique identifier of the gateway terminal template. maxLength: 50 required: &ref_844 - gateway - terminalTemplateId batchClosure: description: "Polymorphic object that contains information about when and how the terminal closes the batch. \n\nThe value of the batchCloseType field determines which variant you should use: \n-\t`automatic` - Terminal automatically closes the batch at a specific time each day. \n- `manual` - Merchant uses the terminal to manually close the batch.\n" discriminator: propertyName: batchCloseType mapping: automatic: '#/components/schemas/schemas-automaticBatchClose' manual: '#/components/schemas/schemas-manualBatchClose' oneOf: - type: object title: automatic description: Indicates how authorized transactions will be batched for settlement properties: &ref_845 batchCloseType: type: string description: Indicates whether batch settlement of authorized transactions are automatically or manually closed enum: - automatic batchCloseTime: type: string description: The time, within the specified timezone, at which the batch automatically closes example: '23:40' maxLength: 5 required: &ref_846 - batchCloseType - batchCloseTime - type: object title: manual description: Indicates how authorized transactions will be batched for settlement properties: &ref_847 batchCloseType: type: string description: Indicates whether batch settlement of authorized transactions are automatically or manually closed enum: - manual required: &ref_848 - batchCloseType applicationSettings: type: object description: Object that contains the application settings for the solution. properties: invoiceNumberPrompt: type: boolean description: Indicates if the terminal should prompt the clerk to provide an invoice number with a sale. clerkPrompt: type: boolean description: Indicates if the terminal should prompt the clerk, for example, if the terminal should prompt when the clerk needs to enter an amount on the terminal. features: type: object description: Object that contains the feature settings for the terminal. properties: tips: description: "Polymorphic object that indicates if the terminal accepts tips. \n\nThe value of the enabled field determines which variant you should use: \n-\t`true` - Terminal allows tips.\n-\t`false` - Terminal doesn't allow tips.\n" discriminator: propertyName: enabled mapping: 'true': '#/components/schemas/tipProcessingEnabled' 'false': '#/components/schemas/tipProcessingDisabled' anyOf: - type: object description: Tip settings properties: &ref_849 enabled: type: boolean description: Indicates if the terminal can accept tips. tipPrompt: type: boolean description: Indicates if the terminal prompts for tips. tipAdjust: type: boolean description: Indicates if a clerk can adjust a tip after the customer completes the sale. suggestedTips: type: object description: Object that contains up to three tip amounts that the terminal displays during a sale. properties: enabled: type: boolean description: Indicates if the terminal displays tip amounts during a sale. tipPercentages: type: array description: Array of the tip amounts that the terminal displays during a sale. items: type: string maxItems: 3 required: &ref_850 - enabled - type: object description: Tip settings properties: &ref_851 enabled: type: boolean description: Indicates if the terminal can accept tips. required: &ref_852 - enabled enhancedProcessing: type: object description: Object that contains details about level two and level three transactions. properties: enabled: type: boolean description: Indicates if the terminal can run level two and level three transactions. transactionDataLevel: type: string description: Indicates if the terminal supports level two or level three transactions. enum: - level2 - level3 maxLength: 6 shippingAddressMode: type: string description: | Indicates the address information that the clerk must provide to qualify for level two or level three data. The value is one of the following: - `fullAddress` - The clerk must provide the full address for the transaction to qualify. - `postalCode` - The clerk must provide a postal code for the transaction to qualify. enum: - fullAddress - postalCode maxLength: 11 required: - enabled ebt: description: "Polymorphic object that indicates if the terminal accepts EBT transactions. \n\nThe value of the enabled field determines which variant you should use: \n-\t`true` - Terminal allows EBT transactions.\n-\t`false` - Terminal doesn't allow EBT transactions.\n" discriminator: propertyName: enabled mapping: 'true': '#/components/schemas/ebtEnabled' 'false': '#/components/schemas/ebtDisabled' anyOf: - type: object description: Object that contains details about EBT transactions. properties: &ref_853 enabled: type: boolean description: Indicates if the terminal accepts Electronic Benefit Transfer (EBT) transactions. ebtType: type: string description: Indicates the type of EBT that the terminal supports. enum: - foodStamp - cash - both maxLength: 9 fnsNumber: type: string description: Food and Nutritional Service (FNS) number that the government assigns to the merchant to allow them to accept Supplemental Nutrition Assistance Program (SNAP) transactions. maxLength: 7 required: &ref_854 - enabled - ebtType - type: object description: Object that contains details about EBT transactions. properties: &ref_855 enabled: type: boolean description: Indicates if the terminal accepts Electronic Benefit Transfer (EBT) transactions. required: &ref_856 - enabled pinDebitCashback: type: boolean description: Indicates if the terminal prompts for cashback on PIN debit transactions. recurringPayments: type: boolean description: Indicates if the terminal can run repeat payments. For more information about repeat payments, go to [Payment Plans](https://docs.payroc.com/guides/take-payments/repeat-payments). paymentLinks: type: object description: Object that contains details about payment links. properties: enabled: type: boolean description: Indicates if the terminal supports payment links. logoUrl: type: string description: URL of the logo image that the merchant wants to display in their payment link email. maxLength: 200 footerNotes: type: string description: String that the merchant wants to display on the footer of their payment link email. maxLength: 2000 required: - enabled preAuthorizations: type: boolean description: Indicates if the terminal can run pre-authorizations. offlinePayments: type: boolean description: Indicates if the terminal can accept payments when it can't connect to the gateway. For more information about offline processing, go to [Offline Processing](https://docs.payroc.com/knowledge/card-payments/offline-processing). required: - enhancedProcessing - pinDebitCashback - ebt taxes: type: array description: Array of tax objects that contains the taxes that apply to the merchant's transactions. items: type: object description: Object that contains a tax rate with a short description of the tax rate. properties: taxRate: description: Rate of tax that the terminal applies to each transaction. type: number format: decimal minimum: 0 maximum: 99.999 taxLabel: type: string description: Short description of the tax rate, for example, "Sales Tax". maxLength: 10 required: - taxRate - taxLabel maxItems: 3 minItems: 0 security: type: object description: Object that contains the tokenization settings and AVS settings for the terminal. properties: tokenization: type: boolean description: Indicates if the terminal can tokenize customer's payment details. For more information about tokenization, go to [Tokenization](https://docs.payroc.com/knowledge/basic-concepts/tokenization). avsPrompt: type: boolean description: Indicates if the terminal should prompt for Address Verification Service (AVS) details when running a transaction. avsLevel: type: string description: Indicates the level of AVS details that the terminal should prompt for. enum: - fullAddress - postalCode maxLength: 11 cvvPrompt: type: boolean description: Indicates if the terminal should prompt for a Card Verfication Value (CVV) when running a transaction. required: - tokenization - avsPrompt - cvvPrompt receiptNotifications: type: object description: Object that indicates if the terminal can send email receipts or text receipts. properties: emailReceipt: type: boolean description: Indicates if the terminal can send receipts by email. smsReceipt: type: boolean description: Indicates if the terminal can send receipts by text message. devices: type: array description: Array of device objects. Each object contains information about a device using the processing terminal's configuration. items: type: object description: Object that contains the details of the device. properties: manufacturer: type: string description: Manufacturer of the terminal. maxLength: 100 model: type: string description: Model of the terminal. maxLength: 100 serialNumber: type: string description: Serial number of the terminal. maxLength: 45 communicationType: type: string description: Indicates how the device communicates with its host. enum: &ref_857 - bluetooth - cellular - ethernet - wifi maxLength: 9 required: - manufacturer - model - serialNumber maxItems: 1 minItems: 0 required: &ref_345 - processingTerminalId - status - timezone - applicationSettings - batchClosure - features examples: processingTerminals: summary: Paginated list of processing terminals description: List of processing terminals associated with a processing account. value: &ref_1027 limit: 2 count: 2 hasMore: true links: - rel: previous method: get href: https://api.payroc.com/v1/processing-accounts/38765/processing-terminals?before=1543&limit=2 - rel: next method: get href: https://api.payroc.com/v1/processing-accounts/38765/processing-terminals?after=87926&limit=2 data: - processingAccountId: '38765' status: active timezone: Pacific/Midway program: Payroc Cloud gateway: gateway: payroc terminalTemplateId: Roc Services_DX8000 batchClosure: batchCloseType: automatic batchCloseTime: '23:40' applicationSettings: clerkPrompt: false invoiceNumberPrompt: true features: tips: enabled: false tipPrompt: false tipAdjust: true suggestedTips: enabled: true tipPercentages: - 15 - 20 enhancedProcessing: enabled: true transactionDataLevel: level2 shippingAddressMode: fullAddress ebt: enabled: true ebtType: foodStamp fnsNumber: '1234567890' pinDebitCashback: false recurringPayments: true paymentLinks: enabled: true logoUrl: LogoPayLink footerNotes: FooterNotesPayLink preAuthorizations: true offlinePayments: true security: tokenization: false avsPrompt: true avsLevel: fullAddress cvvPrompt: true receiptNotifications: emailReceipt: true smsReceipt: false taxes: - taxRate: 6 taxLabel: Sales Tax devices: - manufacturer: Ingenico model: Axium Dx4000 Tsys serialNumber: DX400-1234 communicationType: bluetooth '400': description: Invalid request content: *ref_15 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '404': description: Resource not found content: *ref_18 '406': description: Not acceptable content: *ref_19 '500': description: An error has occured content: *ref_14 /processing-accounts/{processingAccountId}/attachments: post: tags: - Processing accounts summary: Upload attachment to processing account description: | > Before you upload an attachment, make sure that you follow local privacy regulations and get the merchant's consent to process their information. **Note:** You need the ID of the processing account before you can upload an attachment. If you don't know the processingAccountId, go to the [Retrieve a Merchant Platform](https://docs.payroc.com/api/schema/boarding/merchant-platforms/retrieve) method. The attachment must be an uncompressed file under 30MB in one of the following formats: - .bmp, csv, .doc, .docx, .gif, .htm, .html, .jpg, .jpeg, .msg, .pdf, .png, .ppt, .pptx, .tif, .tiff, .txt, .xls, .xlsx In the request, include the attachment that you want to upload and the following information about the attachment: - **type** - Type of attachment that you want to upload. - **description** - Short description of the attachment. In the response, our gateway returns information about the attachment including its upload status and an attachmentId that you can use to [Retrieve the details of the Attachment](https://docs.payroc.com/api/schema/attachments/get-attachment). operationId: createProcessingAccountAttachment parameters: - name: Idempotency-Key in: header required: true 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). schema: *ref_22 examples: *ref_23 - name: processingAccountId in: path description: Unique identifier that we assigned to the processing account. required: true schema: *ref_311 examples: *ref_312 requestBody: content: multipart/form-data: schema: type: object properties: &ref_859 attachment: type: object description: Object that contains details about the attachment. properties: type: type: string description: Type of attachment. enum: - bankingEvidence - questionnairesAndLicenses - merchantStatements - taxDocuments - mpaOrAmendment - proofOfBusiness - financialStatements - personalIdentification - other minLength: 5 maxLength: 25 example: personalIdentification description: type: string description: Short description of the attachment. maxLength: 250 example: Passport as identification for lease agreement metadata: type: object additionalProperties: type: string description: Object that you can send to include custom metadata in the request. example: documentId: '2345' required: - type file: type: string description: File that you want to upload. format: binary required: &ref_860 - attachment - file required: true responses: '201': description: Successful request. We received the attachment. content: application/json: schema: type: object properties: &ref_351 attachmentId: type: string description: Unique identifier that our gateway assigned to the attachment. example: '2587' type: type: string description: Type of attachment. enum: - bankingEvidence - questionnairesAndLicenses - merchantStatements - taxDocuments - mpaOrAmendment - proofOfBusiness - financialStatements - personalIdentification - other minLength: 5 maxLength: 22 example: personalIdentification uploadStatus: type: string description: | Upload status of the attachment. The value is one of the following: - `pending` - We have not yet uploaded the attachment. - `accepted` - We have uploaded the attachment. - `rejected` - We rejected the attachment. enum: - pending - accepted - rejected maxLength: 8 example: pending fileName: type: string description: Name of the file. example: JohnSmithPassport.pdf maxLength: 150 contentType: type: string description: Content type of the file. example: application/pdf maxLength: 76 description: type: string description: Short description of the attachment. example: Passport as identification for lease agreement maxLength: 250 entity: type: object description: Object that contains information about the entity that the attachment is linked to. properties: type: type: string description: Type of entity that the attachment is linked to. enum: - processingAccount maxLength: 17 example: processingAccount id: type: string description: Unique identifier of the entity that the attachment is linked to. example: '12667' maxLength: 50 required: - type - id createdDate: type: string format: date-time description: Date and time that we received your request to upload the attachment. example: '2024-07-02T12:00:00.000Z' lastModifiedDate: type: string format: date-time description: Date and time the attachment was last modified. example: '2024-07-02T12:00:00.000Z' metadata: type: object additionalProperties: type: string description: Object that you can send to include custom metadata in the request. example: passportId: '123456789' required: &ref_352 - attachmentId - uploadStatus - contentType - fileName - entity - type - createdDate - lastModifiedDate headers: location: description: URI reference to created resource. schema: *ref_24 examples: *ref_25 '400': description: Validation error content: application/problem+json: schema: type: object properties: *ref_9 required: *ref_10 examples: validationError: summary: Bad Request description: One or more validation errors occurred value: *ref_11 idempotentKeyMissing: summary: Idempotency key missing description: Idempotency key must be supplied value: *ref_26 idempotentKeyInUse: summary: Idempotency key in use description: Idempotency key in use value: *ref_29 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '404': description: Resource not found content: *ref_18 '406': description: Not acceptable content: *ref_19 '409': description: Conflict content: *ref_104 '413': description: Payload too large content: *ref_343 '415': description: Unsupported media type content: *ref_105 '500': description: An error has occured content: *ref_14 /processing-terminals/{processingTerminalId}: get: tags: - Processing terminals summary: Retrieve processing terminal description: | **Important:** You can retrieve a processing terminal only if the terminal order was created using the Payroc API. Use this method to retrieve information about a processing terminal. To retrieve a processing terminal, you need its processingTerminalId. Our gateway returned the processingTerminalId in the response of the [Create Terminal Order](https://docs.payroc.com/api/schema/boarding/processing-accounts/create-terminal-order) method. **Note:** If you don't have the processingTerminalId, use our [Retrieve Terminal Order](https://docs.payroc.com/api/schema/boarding/terminal-orders/retrieve) method or our [List Processing Terminals](https://docs.payroc.com/api/schema/boarding/processing-accounts/list-processing-terminals) method to search for the processing terminal. Our gateway returns the following information about the processing terminal: - Status indicating whether the terminal is active or inactive. - Configuration settings, including gateway settings and application settings. - Features, receipt settings, and security settings. - Devices that use the processing terminal's configuration. operationId: getProcessingTerminal parameters: - name: processingTerminalId in: path required: true description: Unique identifier that we assigned to the terminal. schema: *ref_96 examples: *ref_97 responses: '200': description: Successful request. Returns the processing terminal. content: application/json: schema: type: object properties: *ref_344 required: *ref_345 examples: processingTerminals: summary: Retrieve processing terminal description: Retrieve a specific processing terminal. value: &ref_1028 processingAccountId: '38765' status: active timezone: Pacific/Midway program: Payroc Cloud gateway: gateway: payroc terminalTemplateId: Roc Services_DX8000 batchClosure: batchCloseType: automatic batchCloseTime: '23:40' applicationSettings: clerkPrompt: false invoiceNumberPrompt: true features: tips: enabled: false tipPrompt: false tipAdjust: true suggestedTips: enabled: true tipPercentages: - 15 - 20 enhancedProcessing: enabled: true transactionDataLevel: level2 shippingAddressMode: fullAddress ebt: enabled: true ebtType: foodStamp fnsNumber: '1234567890' pinDebitCashback: false recurringPayments: true paymentLinks: enabled: true logoUrl: LogoPayLink footerNotes: FooterNotesPayLink preAuthorizations: true offlinePayments: true security: tokenization: false avsPrompt: true avsLevel: fullAddress cvvPrompt: true receiptNotifications: emailReceipt: true smsReceipt: false taxes: - taxRate: 6 taxLabel: Sales Tax devices: - manufacturer: Ingenico model: Axium Dx4000 Tsys serialNumber: DX400-1234 communicationType: bluetooth '400': description: Invalid request content: *ref_15 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '404': description: Resource not found content: *ref_18 '406': description: Not acceptable content: *ref_19 '500': description: An error has occured content: *ref_14 /processing-terminals/{processingTerminalId}/host-configurations: get: tags: - Processing terminals summary: Retrieve host processor configuration description: | Use this method to retrieve the host processor configuration of a processing terminal. Integrate with this method only if you use your own gateway and want to validate the processor configuration. Our gateway returns the configuration settings for the merchant and the payment terminal. operationId: getProcessingTerminalHostConfiguration parameters: - name: processingTerminalId in: path required: true description: Unique identifier that we assigned to the terminal. schema: *ref_96 examples: *ref_97 responses: '200': description: Successful request. Returns the host configuration of the processing terminal. content: application/json: schema: type: object description: Object that contains the terminal's host configuration. properties: &ref_863 processingTerminalId: type: string description: Unique identifier that our gateway assigned to the terminal. example: '0123451001' processingAccountId: type: string description: Unique identifier that we assigned to the processing account. example: '23451' configuration: description: Polymorphic object that contains the host processor configuration. discriminator: propertyName: processor mapping: tsys: '#/components/schemas/tsys' oneOf: - type: object properties: &ref_861 processor: type: string description: Name of the host processor. example: tsys enum: - tsys maxLength: 50 merchant: type: object description: Object that contains the configuration settings for the merchant. properties: posMid: type: string description: Unique identifier that the host processor assigned to the merchant. maxLength: 12 example: '123456789101' chainNumber: type: string description: Number that represents the merchant's chain of locations or stores. maxLength: 6 example: '222222' settlementAgent: type: string description: Unique identifier of the merchant's settlement agent. maxLength: 4 example: '0001' abaNumber: type: string description: Number that identifies the merchant in direct debit requests. maxLength: 12 example: '967854108' binNumber: type: string description: Unique identifier of the merchant's bank. maxLength: 6 example: '888888' agentBankNumber: type: string description: Number of the merchant's bank if it processes transactions on behalf of another entity. maxLength: 6 example: '000001' reimbursementAttribute: type: string description: Indicates if the merchant can accept interlink debit cards. maxLength: 1 example: Z locationNumber: type: string description: Location of the merchant's information. maxLength: 6 example: '000001' required: - posMid - chainNumber - binNumber terminal: type: object description: Object that contains the configuration settings for the terminal. properties: terminalId: type: string description: Unique identifier that the host processor assigned to the terminal. maxLength: 8 example: V500000 terminalNumber: type: string description: Unique identifier of the terminal at the merchant's site. maxLength: 4 example: '1111' authenticationCode: type: string description: Authenticates the terminal's identity with the host processor. minLength: 6 maxLength: 10 example: A1B2C3 sharingGroups: type: string description: Indicates the direct debit networks and EBT networks that the terminal can use. maxLength: 26 example: 3E7HULY8NQWZG motoAllowed: type: boolean description: Indicates if the terminal can run Mail Order/Telephone Order (MOTO) transactions. internetAllowed: type: boolean description: Indicates if the terminal can run e-Commerce transactions. cardPresentAllowed: type: boolean description: Indicates if the terminal can run card present transactions. required: - terminalId - terminalNumber required: &ref_862 - processor - merchant - terminal required: &ref_864 - processingTerminalId - configuration '400': description: Invalid request content: *ref_15 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '404': description: Resource not found content: *ref_18 '406': description: Not acceptable content: *ref_19 '500': description: An error has occured content: *ref_14 /contacts/{contactId}: get: tags: - Contacts summary: Retrieve contact description: "Use this method to retrieve details about a contact. \n\nTo retrieve a contact, you need its contactId. Our gateway returned the contactId in the [Create Processing Account](https://docs.payroc.com/api/schema/boarding/merchant-platforms/create-processing-account) method. \n\n**Note:** If you don't have the contactId, use the [List Contacts](https://docs.payroc.com/api/schema/boarding/processing-accounts/list-contacts) method to search for the contact. \n\nOur gateway returns the following information about a contact: \n\n-\tName and contact method, including their phone number or mobile number. \n-\tRole within the business, for example, if they are a manager. \n" operationId: getContact parameters: - name: contactId in: path description: Unique identifier for the contact. required: true schema: &ref_346 type: integer examples: &ref_347 example: value: 1543 responses: '200': description: Successful request. Returns the requested contact. content: application/json: schema: type: object title: contact required: *ref_313 properties: *ref_314 examples: contact: summary: Contact object description: Contact object value: &ref_1029 contactId: 1543 type: manager firstName: Jane middleName: Helen lastName: Doe identifiers: - type: nationalId value: xxxxx4320 contactMethods: - type: email value: jane.doe@example.com - type: phone value: '2025550164' - type: mobile value: '8445557624' - type: fax value: '2025550110' '400': description: Invalid request content: *ref_15 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '404': description: Resource not found content: *ref_18 '500': description: An error has occured content: *ref_14 put: tags: - Contacts summary: Update contact description: "Use this method to update a contact of a processing account. \n\nTo update a contact, you need its contactId. Our gateway returned the contactId in the response of the [Create Processing Account](https://docs.payroc.com/api/schema/boarding/merchant-platforms/create-processing-account) method. \n\n**Note:** If you don't have the contactId, use our [List Contacts](https://docs.payroc.com/api/schema/boarding/processing-accounts/list-contacts) method to search for the contact. \n\nYou can update the following details about a contact: \n\n-\tFirst name and last name. \n-\tContact details, including their phone number or mobile number. \n-\tIdentification details, including their identification type and number. \n-\tRole within the business, for example, if they are a manager. \n" operationId: updateContact parameters: - name: contactId in: path description: Unique identifier for the contact. required: true schema: *ref_346 examples: *ref_347 requestBody: content: application/json: schema: type: object title: contact required: *ref_313 properties: *ref_314 examples: updateContact: summary: Update contact description: Update a specific contact. value: &ref_1030 type: manager firstName: Jane middleName: Helen lastName: Doe identifiers: - type: nationalId value: 000-00-4320 contactMethods: - type: email value: jane.doe@example.com responses: '204': description: Successful request. We updated the contact. '400': description: Validation errors. content: application/problem+json: schema: type: object properties: *ref_9 required: *ref_10 examples: validationError: summary: Bad Request description: One or more validation errors occurred value: *ref_11 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '404': description: Resource not found content: *ref_18 '406': description: Not acceptable content: *ref_19 '500': description: An error has occured content: *ref_14 delete: tags: - Contacts summary: Delete contact description: | Use this method to delete a contact associated with a processing account. To delete a contact, you need their contactId. Our gateway returned the contactId in the response of the [Create Processing Account](https://docs.payroc.com/api/schema/boarding/merchant-platforms/create-processing-account) method. **Note:** If you don’t have the contactId, use our [Retrieve Processing Account](https://docs.payroc.com/api/schema/boarding/processing-accounts/retrieve) method or our [List Contacts](https://docs.payroc.com/api/schema/boarding/processing-accounts/list-contacts) method to search for the contact. operationId: deleteContact parameters: - name: contactId in: path description: Unique identifier for the contact. required: true schema: *ref_346 examples: *ref_347 responses: '204': description: Successful request. We deleted the contact. '400': description: Invalid request content: *ref_15 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '404': description: Resource not found content: *ref_18 '500': description: An error has occured content: *ref_14 /event-subscriptions: get: tags: - Event Subscriptions summary: List event subscriptions description: | Use this method to return a [paginated](https://docs.payroc.com/api/pagination) list of event subscriptions that are linked to your ISV account. **Note:** If you want to view the details of a specific event subscription and you have its id, use our [Retrieve Event Subscription](https://docs.payroc.com/api/schema/notifications/event-subscriptions/retrieve) method. Use query parameters to filter the list of results that we return, for example, to search for subscriptions with a specific status or an event type. Our gateway returns the following information about each subscription in the list: - Event types that you have subscribed to. - Whether you have enabled notifications for the subscription. - How we contact you when an event occurs, including the endpoint that send notifications to. - If there are any issues when we try to send you a notification, for example, if we can't contact your endpoint. For each event subscription, we also return its id, which you can use to perform follow-on actions. operationId: listEventSubscriptions parameters: - name: status in: query description: Filter event subscriptions by subscription status. schema: &ref_518 type: string enum: - registered - suspended - failed examples: &ref_519 example: value: registered - name: event in: query description: Filter event subscriptions by an event type. For a list of event types, go to [Events List](https://docs.payroc.com/knowledge/events/events-list). schema: &ref_520 type: string examples: &ref_521 example: value: processingAccount.status.changed responses: '200': description: Successful request. Returns a list of event subscriptions. content: application/json: schema: type: object title: paginated event subscriptions allOf: &ref_869 - type: object description: Contains the pagination properties that you use to navigate through a list of results. properties: *ref_38 - type: object properties: data: type: array description: Array of eventSubscription objects. items: type: object title: Event Subscription properties: &ref_348 id: type: integer format: int64 description: Unique identifier that we assigned to the event subscription. readOnly: true example: 2565435189324 enabled: type: boolean description: | Indicates if we should notify you when the event occurs. The value is one of the following: - `true` - We notify you when the event occurs. - `false` - We don't notify you when the event occurs. example: true status: type: string description: | Status of the subscription. We return one of the following values: - `registered` - You have set up the subscription, and we will notify you when an event occurs. - `suspended` - We have deactivated the event subscription, and we won't notify you when an event occurs. - `failed` - We couldn't contact your URI endpoint. We email the supportEmailAddress. enum: - registered - suspended - failed readOnly: true example: registered eventTypes: type: array description: Array of events that you want to subscribe to. For a list of events, go to [Events List](https://docs.payroc.com/knowledge/events/events-list). items: type: string minLength: 1 example: - processingAccount.status.changed notifications: type: array description: Array of polymorphic notification objects that contain information about how we contact you when an event occurs. items: type: object title: Notification method oneOf: &ref_867 - type: object properties: &ref_865 type: type: string description: | Type of notification method. **Note:** To receive notifications by webhook, your server must be able to handle POST requests. enum: - webhook example: webhook uri: type: string description: Public endpoint that we send notifications to. example: https://my-server/notification/endpoint secret: type: string description: | String that we send with a notification so that you can ensure it is a valid notification from our gateway. We include the value in the Payroc-Secret header parameter in the webhook call. **Note:** In the response, we truncate the secret to the last 16 characters and mask the first 10 characters. minLength: 16 maxLength: 64 example: aBcD1234eFgH5678iJkL9012mNoP3456 supportEmailAddress: type: string description: Email address of the person or team that we contact if we can't deliver notifications. required: &ref_866 - type - uri - secret - supportEmailAddress discriminator: &ref_868 propertyName: type mapping: webhook: '#/components/schemas/webhook' metadata: type: object description: Object that you can send to include custom data in the request. For more information about how to use metadata, go to [Metadata](https://docs.payroc.com/api/metadata). example: yourCustomField: abc123 required: &ref_349 - enabled - eventTypes - notifications examples: paginatedList: summary: Paginated list of Event subscriptions description: Example of a paginated list of event subscriptions value: &ref_1031 limit: 10 count: 2 hasMore: false links: - rel: next method: get href: https://api.payroc.com/v1/event-subscriptions?after=10&limit=10 data: - id: 2565435189324 enabled: true status: registered eventTypes: - processingAccount.status.changed notifications: - type: webhook uri: https://my-service/notification/endpoint secret: '**********oP3456' supportEmailAddress: jane.doe@example.com metadata: yourCustomField: abc123 - id: 2565435189325 enabled: true status: registered eventTypes: - processingAccount.riskStatus.changed notifications: - type: webhook uri: https://my-service/notification/endpoint secret: '**********oP3456' supportEmailAddress: jane.doe@example.com metadata: yourCustomField: abc123 '400': description: Invalid request content: *ref_15 '401': description: Identity could not be verified content: *ref_12 '404': description: Resource not found content: *ref_18 '500': description: An error has occured content: *ref_14 post: tags: - Event Subscriptions summary: Create event subscription description: | Use this method to create an event subscription that we use to notify you when an event occurs, for example, when we change the status of a processing account. In the request, include the events that you want to subscribe to and the public endpoint that we send event notifications to. For a complete list of events that you can subscribe to, go to [Events List](https://docs.payroc.com/knowledge/events/events-list). In the response, our gateway returns the id of the event subscription, which you can use to perform follow-on actions. operationId: createEventSubscription parameters: - name: Idempotency-Key in: header required: true 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). schema: *ref_22 examples: *ref_23 requestBody: content: application/json: schema: type: object title: Event Subscription properties: *ref_348 required: *ref_349 examples: createEventSubscription: summary: Create event subscription description: Create an event subscription value: &ref_1032 enabled: true eventTypes: - processingAccount.status.changed notifications: - type: webhook uri: https://my-server/notification/endpoint secret: aBcD1234eFgH5678iJkL9012mNoP3456 supportEmailAddress: jane.doe@example.com metadata: yourCustomField: abc123 createEventSubscriptionMetadata: summary: Create event subscription with metadata description: Create an event subscription value: &ref_1033 enabled: true eventTypes: - processingAccount.status.changed notifications: - type: webhook uri: https://my-server/notification/endpoint secret: aBcD1234eFgH5678iJkL9012mNoP3456 supportEmailAddress: jane.doe@example.com metadata: responsiblePerson: Jane Doe responses: '201': description: Successful request. We created the event subscription. headers: Location: description: URI reference to created resource schema: &ref_1045 type: string content: application/json: schema: type: object title: Event Subscription properties: *ref_348 required: *ref_349 examples: createdEventSubscription: summary: Event subscription created description: Example of a created event subscription. value: &ref_1034 id: 2565435189324 enabled: true status: registered eventTypes: - processingAccount.status.changed notifications: - type: webhook uri: https://my-service/notification/endpoint secret: '**********oP3456' supportEmailAddress: jane.doe@example.com metadata: yourCustomField: abc123 eventSubscriptionCreatedMetadata: summary: Event subscription created metadata description: Example of a created event subscription. value: &ref_1035 id: 2565435189324 enabled: true status: registered eventTypes: - processingAccount.status.changed notifications: - type: webhook uri: https://my-server/notification/endpoint secret: '**********oP3456' supportEmailAddress: jane.doe@example.com metadata: responsiblePerson: Jane Doe '400': description: Validation error content: application/problem+json: schema: type: object properties: *ref_9 required: *ref_10 examples: validationError: summary: Bad Request description: One or more validation errors occurred value: *ref_11 idempotentKeyMissing: summary: Idempotency key missing description: Idempotency key must be supplied value: *ref_26 '401': description: Identity could not be verified content: *ref_12 '404': description: Resource not found content: *ref_18 '406': description: Not acceptable content: *ref_19 '409': description: Conflict content: application/problem+json: schema: type: object properties: *ref_27 required: *ref_28 examples: idempotentKeyInUse: summary: Idempotency key in use description: Idempotency key in use value: *ref_29 '500': description: An error has occured content: *ref_14 /event-subscriptions/{subscriptionId}: parameters: - name: subscriptionId in: path description: | Unique identifier that we assigned to the event subscription. **Note:** Our gateway returned the subscriptionId in the id field in the response of the [Create Event Subscription](https://docs.payroc.com/api/schema/notifications/event-subscriptions/create) method. required: true schema: &ref_522 type: integer format: int32 examples: &ref_523 example: value: 7654 get: tags: - Event Subscriptions summary: Retrieve event subscription description: | Use this method to retrieve the details of an event subscription. In your request, include the subscriptionId that we sent to you when we created the event subscription. **Note:** If you don't know the subscriptionId of the event subscription, go to [List event subscriptions](#listEventSubscriptions). operationId: getEventSubscription responses: '200': description: Returns the event subscription object. content: application/json: schema: type: object title: Event Subscription properties: *ref_348 required: *ref_349 examples: eventSubscription: summary: Event subscription description: Example of an event subscription. value: &ref_1036 id: 2565435189324 enabled: true status: registered eventTypes: - processingAccount.status.changed notifications: - type: webhook uri: https://my-service/notification/endpoint secret: '**********oP3456' supportEmailAddress: jane.doe@example.com metadata: yourCustomField: abc123 '400': description: Invalid request content: *ref_15 '401': description: Identity could not be verified content: *ref_12 '404': description: Resource not found content: *ref_18 '500': description: An error has occured content: *ref_14 put: tags: - Event Subscriptions summary: Update event subscription description: | Use this method to update the details of an event subscription. To update an event subscription, you need its subscriptionId. Our gateway returned the subscriptionId in the response of the [Create Event Subscription](https://docs.payroc.com/api/schema/notifications/event-subscriptions/create) method. **Note:** If you don’t have the subscriptionId, use our [List Event Subscriptions](https://docs.payroc.com/api/schema/notifications/event-subscriptions/list) method to search for the event subscription. You can update the following details about an event subscription: - Status of the event subscription. - Events that you have subscribed to. For a list of events that you can subscribe to, go to [Events list](https://docs.payroc.com/knowledge/events/events-list). - Information about how we contact you when an event occurs. operationId: updateEventSubscription requestBody: content: application/json: schema: type: object title: Event Subscription properties: *ref_348 required: *ref_349 examples: updateEventSubscription: summary: Update event subscription description: Update an event subscription value: &ref_1037 enabled: true eventTypes: - processingAccount.status.changed notifications: - type: webhook uri: https://my-server/notification/endpoint secret: aBcD1234eFgH5678iJkL9012mNoP3456 supportEmailAddress: jane.doe@example.com metadata: yourCustomField: abc123 responses: '204': description: Successful request. We updated the event subscription. '400': description: Invalid request content: *ref_15 '401': description: Identity could not be verified content: *ref_12 '404': description: Resource not found content: *ref_18 '406': description: Not acceptable content: *ref_19 '500': description: An error has occured content: *ref_14 patch: tags: - Event Subscriptions summary: Partially update event subscription description: | Use this method to partially update an event subscription. Structure your request to follow the [RFC 6902](https://datatracker.ietf.org/doc/html/rfc6902) standard. To update an event subscription, you need its subscriptionId. Our gateway returned the subscriptionId in the id field in the response of the [Create Event Subscription](https://docs.payroc.com/api/schema/notifications/event-subscriptions/create) method. **Note:** If you don't have the subscriptionId, use our [List Event Subscriptions](https://docs.payroc.com/api/schema/notifications/event-subscriptions/list) method to search for the subscription. You can update the following properties of an event subscription: - **eventTypes** - Subscribe to new events or remove events that you are subscribed to. - **notifications** - Information about your endpoint and who we email if we can't contact your endpoint. - **enabled** - Turn on or turn off notifications for the subscription. operationId: patchEventSubscription parameters: - name: Idempotency-Key in: header required: true 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). schema: *ref_22 examples: *ref_23 requestBody: content: application/json: schema: type: array description: A JSON Patch document as defined by RFC 6902. items: *ref_101 example: *ref_102 examples: patchEventSubscriptionRealistic: summary: Partially update event subscription description: | Partially update an existing event subscription. Structure your request to follow the RFC 6902 standard. value: &ref_1038 - op: replace path: /enabled value: false responses: '200': description: Successful request. We updated the event subscription. content: application/json: schema: type: object title: Event Subscription properties: *ref_348 required: *ref_349 examples: patchedEventSubscription: summary: Patched event subscription description: Example of a patched event subscription. value: &ref_1039 id: 2565435189324 enabled: false status: registered eventTypes: - processingAccount.status.changed notifications: - type: webhook uri: https://my-service/notification/endpoint secret: '**********oP3456' supportEmailAddress: jane.doe@example.com metadata: yourCustomField: abc123 '400': description: Validation error content: application/problem+json: schema: type: object properties: *ref_9 required: *ref_10 examples: validationError: summary: Bad Request description: One or more validation errors occurred value: *ref_11 idempotentKeyMissing: summary: Idempotency key missing description: Idempotency key must be supplied value: *ref_26 '401': description: Identity could not be verified content: *ref_12 '404': description: Resource not found content: *ref_18 '406': description: Not acceptable content: *ref_19 '409': description: Conflict content: application/problem+json: schema: type: object properties: *ref_27 required: *ref_28 examples: idempotentKeyInUse: summary: Idempotency key in use description: Idempotency key in use value: *ref_29 '500': description: An error has occured content: *ref_14 delete: tags: - Event Subscriptions summary: Delete event subscription description: | Use this method to delete an event subscription. > **Important:** After you delete an event subscription, you can’t recover it. You won't receive event notifications from the event subscription. To delete an event subscription, you need its subscriptionId. Our gateway returned the subscriptionId in the response of the [Create Event Subscription](https://docs.payroc.com/api/schema/notifications/event-subscriptions/create) method. If you want to stop receiving event notifications but don't want to delete the event subscription, use our [Update Event Subscription](https://docs.payroc.com/api/schema/notifications/event-subscriptions/update) method to deactivate it. operationId: deleteEventSubscription responses: '204': description: Successful request. We deleted the event subscription. '400': description: Invalid request content: *ref_15 '401': description: Identity could not be verified content: *ref_12 '404': description: Resource not found content: *ref_18 '500': description: An error has occured content: *ref_14 /terminal-orders/{terminalOrderId}: get: tags: - Terminal orders summary: Retrieve terminal order description: | Use this method to retrieve information about a terminal order. To retrieve a terminal order, you need it's terminalOrderId. Our gateway returned the terminalOrderId in the response of the [Create Terminal Order](https://docs.payroc.com/api/schema/boarding/processing-accounts/create-terminal-order) method. **Note**: If you don't have the terminalOrderId, use our [List Terminal Orders](https://docs.payroc.com/api/schema/boarding/processing-accounts/list-terminal-orders) method to search for the terminal order. Our gateway returns the following information about the terminal order: - Status of the order - Items in the order - Training provider - Shipping information **Note**: You can subscribe to our terminalOrder.status.changed event to get notifications when we update the status of a terminal order. For more information about how to subscribe to events, go to [Events Subscriptions](https://docs.payroc.com/guides/board-merchants/event-subscriptions). operationId: getTerminalOrder parameters: - name: terminalOrderId in: path description: Unique identifier of the terminal order. required: true schema: &ref_524 type: string examples: &ref_525 example: value: '12345' responses: '200': description: Successful request. Returns the terminal order. content: application/json: schema: type: object properties: *ref_341 required: *ref_342 examples: terminalOrder: summary: Terminal order description: Terminal order value: &ref_1040 terminalOrderId: '12345' status: open trainingProvider: payroc shipping: preferences: method: nextDay saturdayDelivery: true address: recipientName: Recipient Name businessName: Company Ltd addressLine1: 1 Example Ave. addressLine2: Example Address Line 2 city: Chicago state: Illinois postalCode: '60056' email: example@mail.com phone: '2025550164' orderItems: - type: solution solutionTemplateId: Roc Services_DX8000 solutionQuantity: 1 deviceCondition: new solutionSetup: timezone: America/Chicago industryTemplateId: Retail gatewaySettings: merchantPortfolioId: Company Ltd merchantTemplateId: Company Ltd Merchant Template userTemplateId: Company Ltd User Template terminalTemplateId: Company Ltd Terminal Template applicationSettings: clerkPrompt: false security: refundPassword: true keyedSalePassword: false reversalPassword: true deviceSettings: numberOfMobileUsers: 2 communicationType: wifi batchClosure: batchCloseType: automatic batchCloseTime: '23:40' receiptNotifications: emailReceipt: true smsReceipt: false taxes: - taxRate: 6 taxLabel: Sales Tax tips: enabled: false tokenization: true links: - processingTerminalId: 38765 link: rel: processingTerminal method: get href: https://api.payroc.com/v1/processing-terminals/38765 '400': description: Invalid request content: *ref_15 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '404': description: Resource not found content: *ref_18 '406': description: Not acceptable content: *ref_19 '500': description: An error has occured content: *ref_14 /ach-deposits: get: tags: - Settlement summary: List ACH deposits description: | Use this method to return a [paginated](https://docs.payroc.com/api/pagination) list of ACH deposits that we paid to your merchants. **Note:** If you want to view the details of a specific ACH deposit and you have its achDepositId, use our [Retrieve ACH Deposit](https://docs.payroc.com/api/schema/reporting/settlement/retrieve-ach-deposit) method. Use query parameters to filter the list of results that we return, for example, to search for ACH deposits that we paid to a specific merchant. > **Important:** You must provide a value for the date query parameter. Our gateway returns the following information about each ACH deposit in the list: - Merchant that we sent the ACH deposit to. - Total amount that we paid the merchant. - Breakdown of sales, returns, and fees. operationId: getAchDeposits parameters: - name: before in: query description: | Return the previous page of results before the value that you specify. You can’t send the before parameter in the same request as the after parameter. schema: *ref_32 examples: *ref_33 - name: after in: query description: | Return the next page of results after the value that you specify. You can’t send the after parameter in the same request as the before parameter. schema: *ref_34 examples: *ref_35 - name: limit in: query description: Limit the maximum number of results that we return for each page. schema: *ref_36 examples: *ref_37 - name: date in: query required: true description: Filter results by the date that the merchant received the ACH deposit. schema: type: string format: date example: '2024-07-02' - name: merchantId in: query description: Filter results by the unique identifier that the processor assigned to the merchant. schema: *ref_64 examples: *ref_65 responses: '200': description: Successful request. Returns a paginated list of ACH deposits. content: application/json: schema: type: object allOf: - type: object description: Contains the pagination properties that you use to navigate through a list of results. properties: *ref_38 - type: object properties: data: type: array description: Array of ACH deposit objects. items: type: object title: ACH deposit description: Object that contains information about the ACH deposit. properties: &ref_350 achDepositId: type: integer description: Unique identifier that we assigned to the ACH deposit. example: 99 associationDate: type: string format: date description: Date that we sent the transactions to the card brands for clearing. The format of this value is **YYYY-MM-DD**. example: '2024-07-02' achDate: type: string format: date description: Date that we sent the ACH deposit. The format of this value is **YYYY-MM-DD**. example: '2024-07-02' paymentDate: type: string format: date description: Date that the merchant received the ACH deposit. The format of this value is **YYYY-MM-DD**. example: '2024-07-02' transactions: type: integer description: Number of transactions in the ACH deposit. example: 20 sales: type: integer description: Amount of sales in the ACH deposit. We return the value in the currency's lowest denomination, for example, cents. example: 5000 returns: type: integer description: Amount of returns in the ACH deposit. We return the value in the currency's lowest denomination, for example, cents. example: 100 dailyFees: type: integer description: Amount of fees that were applied to the transactions in the ACH deposit. We return the value in the currency's lowest denomination, for example cents. example: 100 heldSales: type: integer description: Amount of funds that we held if the merchant was in full suspense. We return the value in the currency's lowest denomination, for example, cents. example: 100 achAdjustment: type: integer description: Amount of adjustments that we made to the ACH deposit. We return the value in the currency's lowest denomination, for example, cents. example: 100 holdback: type: integer description: Amount of funds that we held as reserve from the ACH deposit. We return the value in the currency's lowest denomination, for example, cents. example: 100 reserveRelease: type: integer description: Amount of funds that we released from holdback. We return the value in the currency's lowest denomination, for example, cents. example: 100 netAmount: type: integer description: Total amount that we paid the merchant after fees and adjustments. We return the value in the currency's lowest denomination, for example, cents. example: 5000 merchant: type: object title: merchant summary description: Object that contains information about the merchant. properties: *ref_68 example: *ref_69 links: type: array items: type: object readOnly: true description: Object that contains HATEOAS links for the resource. properties: *ref_4 required: *ref_5 example: *ref_6 example: - rel: achDepositFees method: get href: https://api.payroc.com/v1/ach-deposit-fees?achDepositId=99&merchantId=4525644354 required: - data examples: paginatedList: summary: Paginated ACH deposits value: &ref_1041 limit: 2 count: 1 hasMore: false links: - rel: previous method: get href: https://api.payroc.com/v1/ach-deposits?before=65&limit=2&date=2024-07-02 data: - achDepositId: 99 associationDate: '2024-07-02' achDate: '2024-07-02' paymentDate: '2024-07-02' transactions: 10 sales: 50000 returns: 10000 dailyFees: 1000 heldSales: 1000 achAdjustment: 1000 holdback: 1000 reserveRelease: 500 netAmount: 36500 merchant: merchantId: '4525644354' doingBusinessAs: Pizza Doe processingAccountId: 38765 link: rel: processingAccount method: get href: https://api.payroc.com/v1/processing-accounts/38765 links: - rel: achDepositFees method: get href: https://api.payroc.com/v1/ach-deposit-fees?achDepositId=99&merchantId=4525644354 noActivity: summary: No records found description: Valid request, but no records match the criteria. value: *ref_55 '400': description: Validation error content: application/problem+json: schema: type: object properties: *ref_9 required: *ref_10 examples: parameterError: summary: Bad Request description: One or more validation errors occurred value: *ref_70 paginationError: summary: Bad Request description: One or more validation errors occurred value: *ref_71 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '406': description: Not acceptable content: *ref_19 '500': description: An error has occured content: *ref_14 /ach-deposits/{achDepositId}: get: tags: - Settlement summary: Retrieve ACH deposit description: | Use this method to retrieve information about an ACH deposit that we paid to a merchant. **Note:** To retrieve an ACH deposit, you need its achDepositId. If you don't have the achDepositId, use our [List ACH Deposits](https://docs.payroc.com/api/schema/reporting/settlement/list-ach-deposits) method to search for the ACH deposit. Our gateway returns the following information about the ACH deposit: - Merchant that we sent the ACH deposit to. - Total amount that we paid the merchant. - Breakdown of sales, returns, and fees. operationId: getAchDeposit parameters: - name: achDepositId description: Unique identifier of the ACH deposit. in: path required: true schema: &ref_526 type: integer examples: &ref_527 example: value: 99 responses: '200': description: Successful request. Returns the requested ACH deposit. content: application/json: schema: type: object title: ACH deposit description: Object that contains information about the ACH deposit. properties: *ref_350 example: summary: Retrieve ACH deposit value: achDepositId: 99 associationDate: '2024-07-02' achDate: '2024-07-02' paymentDate: '2024-07-02' transactions: 10 sales: 50000 returns: 10000 dailyFees: 1000 heldSales: 1000 achAdjustment: 1000 holdback: 1000 reserveRelease: 500 netAmount: 36500 merchant: merchantId: '4525644354' doingBusinessAs: Pizza Doe processingAccountId: 38765 link: rel: processingAccount method: get href: https://api.payroc.com/v1/processing-accounts/38765 links: - rel: achDepositFees method: get href: https://api.payroc.com/v1/ach-deposit-fees?achDepositId=99&merchantId=4525644354 '400': description: Validation error content: application/problem+json: schema: type: object properties: *ref_9 required: *ref_10 examples: idError: summary: Bad Request description: One or more validation errors occurred value: &ref_1042 type: https://docs.payroc.com/api/errors#bad-request title: Bad request status: 400 detail: One or more validation errors occurred, see error section for more info errors: - parameter: achDepositId detail: invalid value message: Expected integer, got abc '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '404': description: Resource not found content: *ref_18 '406': description: Not acceptable content: *ref_19 '500': description: An error has occured content: *ref_14 /ach-deposit-fees: get: tags: - Settlement summary: List ACH deposit fees description: | Retrieve a list of ACH deposit fees. > **Important:** You must provide a value for either the 'date' query parameter or the 'achDepositId' query parameter. operationId: getAchDepositFees parameters: - name: before in: query description: | Return the previous page of results before the value that you specify. You can’t send the before parameter in the same request as the after parameter. schema: *ref_32 examples: *ref_33 - name: after in: query description: | Return the next page of results after the value that you specify. You can’t send the after parameter in the same request as the before parameter. schema: *ref_34 examples: *ref_35 - name: limit in: query description: Limit the maximum number of results that we return for each page. schema: *ref_36 examples: *ref_37 - name: date in: query description: Date to retrieve results from. You must provide either the 'achDepositId' or the 'date'. schema: type: string format: date example: '2024-07-02' - name: achDepositId description: Unique identifier of the ACH deposit. You must provide either the 'achDepositId' or the 'date'. in: query schema: &ref_528 type: integer examples: &ref_529 example: value: 99 - name: merchantId in: query description: Filter results by the unique identifier that the processor assigned to the merchant. schema: *ref_64 examples: *ref_65 responses: '200': description: Successful request. Returns a paginated list of ACH deposit fees. content: application/json: schema: type: object allOf: - type: object description: Contains the pagination properties that you use to navigate through a list of results. properties: *ref_38 - type: object properties: data: type: array description: Array of ACH deposit objects. items: type: object title: ACH deposit fee description: Object that contains information about the ACH deposit fee. properties: &ref_872 associationDate: type: string format: date description: Date that we sent the transaction to the cards brands for clearing. The format of this value is **YYYY-MM-DD**. example: '2024-07-02' adjustmentDate: type: string format: date description: Date of the adjustment. The format of this value is **YYYY-MM-DD**. example: '2024-07-02' description: type: string description: Description of the ACH deposit fee. example: Month-End Fees Credit Processing amount: type: integer description: Total value of ACH deposit fee. example: 100 merchant: type: object title: merchant summary description: Object that contains information about the merchant. properties: *ref_68 example: *ref_69 achDeposit: type: object title: ACH deposit summary description: Object that contains information about the ACH deposit. properties: &ref_870 achDepositId: type: integer description: Unique identifier of the ACH deposit. example: 99 link: type: object readOnly: true description: Object that contains HATEOAS links for the resource. properties: *ref_4 required: *ref_5 example: *ref_6 example: &ref_871 achDepositId: 99 link: rel: achDeposit method: get href: https://api.payroc.com/v1/ach-deposits/99?merchantId=4525644354 required: - data examples: paginatedList: summary: Paginated ACH deposit fees value: &ref_1043 limit: 2 count: 1 hasMore: false links: - rel: previous method: get href: https://api.payroc.com/v1/ach-deposit-fees?before=65&limit=2&date=2024-07-02 data: - associationDate: '2024-07-02' adjustmentDate: '2024-07-02' description: ACH Deposit Fee amount: 500 merchant: merchantId: '4525644354' doingBusinessAs: Pizza Doe processingAccountId: 38765 link: rel: processingAccount method: get href: https://api.payroc.com/v1/processing-accounts/38765 achDeposit: achDepositId: 99 link: rel: achDeposit method: get href: https://api.payroc.com/v1/ach-deposits/99?merchantId=4525644354 noActivity: summary: No records found description: Valid request, but no records match the criteria. value: *ref_55 '400': description: Validation error content: application/problem+json: schema: type: object properties: *ref_9 required: *ref_10 examples: parameterError: summary: Bad Request description: One or more validation errors occurred value: *ref_70 paginationError: summary: Bad Request description: One or more validation errors occurred value: *ref_71 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '406': description: Not acceptable content: *ref_19 '500': description: An error has occured content: *ref_14 /attachments/{attachmentId}: get: tags: - Attachments summary: Retrieve attachment description: | Use this method to retrieve the details of an attachment. To retrieve the details of an attachment you need its attachmentId. Our gateway returned the attachmentId in the response of the method that you used to upload the attachment. Our gateway returns information about the attachment, including its upload status and the entity that the attachment is linked to. Our gateway doesn't return the file that you uploaded. operationId: getAttachment parameters: - name: attachmentId in: path description: Unique identifier of the attachment required: true schema: &ref_530 type: string example: '12876' responses: '200': description: Successful request. Returns the attachment. content: application/json: schema: type: object properties: *ref_351 required: *ref_352 examples: attachment: summary: Upload Attachment description: Upload a file attachment value: &ref_1044 attachmentId: '15387' type: personalIdentification uploadStatus: accepted fileName: oliviaDoePassport.pdf contentType: application/pdf description: Passport for Olivia Doe entity: type: processingAccount id: '2585' createdDate: '2025-09-18T10:19:18.522Z' lastModifiedDate: '2025-09-18T10:19:18.522Z' metadata: passportId: '123456789' '400': description: Invalid request content: *ref_15 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '404': description: Resource not found content: *ref_18 '406': description: Not acceptable content: *ref_19 '500': description: An error has occured content: *ref_14 components: securitySchemes: bearerAuth: type: http description: 'Example: Authorization: Bearer ' scheme: bearer bearerFormat: JWT parameters: before: name: before in: query description: | Return the previous page of results before the value that you specify. You can’t send the before parameter in the same request as the after parameter. schema: *ref_32 examples: *ref_33 after: name: after in: query description: | Return the next page of results after the value that you specify. You can’t send the after parameter in the same request as the before parameter. schema: *ref_34 examples: *ref_35 limit: name: limit in: query description: Limit the maximum number of results that we return for each page. schema: *ref_36 examples: *ref_37 idempotencyKey: name: Idempotency-Key in: header required: true 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). schema: *ref_22 examples: *ref_23 recipientId: name: recipientId description: Unique identifier that we assigned to the funding recipient. in: path required: true schema: *ref_16 example: 234 fundingAccountId: name: fundingAccountId in: path required: true description: Unique identifier of the funding account. schema: *ref_39 examples: *ref_40 ownerId: name: ownerId in: path description: Unique identifier that we assigned to the owner. required: true schema: *ref_41 examples: *ref_42 pricingIntentId: in: path name: pricingIntentId required: true description: Unique identifier that we assigned to the pricing intent. schema: *ref_353 examples: *ref_354 dateFrom: name: dateFrom in: query description: Filter by funding instructions sent after a specific date. Send a value in **YYYY-MM-DD** format. required: true schema: *ref_355 examples: *ref_356 dateTo: name: dateTo in: query required: true description: Filter by funding instructions sent before a specific date. Send a value in **YYYY-MM-DD** format. schema: *ref_357 examples: *ref_358 instructionId: name: instructionId in: path required: true description: Unique identifier that we assigned to the funding instruction. schema: *ref_359 examples: *ref_360 merchantId: name: merchantId in: query description: Filter results by the unique identifier that the processor assigned to the merchant. schema: *ref_64 examples: *ref_65 parameters-dateFrom: name: dateFrom in: query description: Filter by activity after a specific date. Send a value in **YYYY-MM-DD** format. required: true schema: *ref_361 examples: *ref_362 parameters-dateTo: name: dateTo in: query required: true description: Filter by activity before a specific date. Send a value in **YYYY-MM-DD** format. schema: *ref_363 examples: *ref_364 date: name: date in: query required: true description: Filter batches by the date that they were submitted. The format of this value is **YYYY-MM-DD**. schema: *ref_365 examples: *ref_366 batchId: name: batchId in: path required: true description: Unique identifier that we assigned to the batch. style: simple schema: *ref_367 examples: *ref_368 keyDate: name: date in: query description: | Filter transactions by the date that the merchant submitted the batch that contains the transaction. The format of this value is **YYYY-MM-DD**. You must provide either the batchId or the date. schema: *ref_73 examples: *ref_74 batchIdQuery: name: batchId in: query description: | Filter transactions by the unique identifier of the batch that contains the transaction. You must provide either the batchId or the date. schema: *ref_75 examples: *ref_76 transactionType: name: transactionType in: query description: Filter transactions by transaction type. schema: *ref_369 examples: *ref_370 transactionId: name: transactionId description: Unique identifier of the transaction. in: path required: true schema: *ref_371 examples: *ref_372 authorizationId: name: authorizationId description: Unique identifier of the authorization. in: path required: true schema: *ref_373 examples: *ref_374 parameters-date: name: date in: query required: true description: Filter results by the date that the dispute was submitted. schema: *ref_375 examples: *ref_376 disputeId: name: disputeId description: Unique identifier of the dispute. in: path required: true schema: *ref_377 examples: *ref_378 processingTerminalIdPath: name: processingTerminalId in: path required: true description: Unique identifier that we assigned to the terminal. schema: *ref_96 examples: *ref_97 merchantReference: name: merchantReference in: query description: Filter results by the unique identifier that the merchant assigned to the payment link. schema: *ref_379 examples: *ref_380 linkType: name: linkType in: query description: Filter results by the type of link. Send a value of singleUse or multiUse. schema: *ref_381 examples: *ref_382 chargeType: name: chargeType in: query description: | Filter results by the user that entered the amount. Send one of the following values: - prompt - Customer entered the amount. - preset - Merchant entered the amount. schema: *ref_383 examples: *ref_384 payment-link-status: name: status in: query description: Filter results by the status of the payment link. Send a value of active, completed,deactived, or expired. schema: *ref_385 examples: *ref_386 recipientName: name: recipientName in: query description: Filter results by the customer's name. schema: *ref_108 examples: *ref_109 recipientEmail: name: recipientEmail in: query description: Filter results by the customer's email address. schema: *ref_110 examples: *ref_111 createdOn: name: createdOn in: query description: Filter results by the link's created date. Send a value in **YYYY-MM-DD** format. schema: *ref_387 examples: *ref_388 expiresOn: name: expiresOn in: query description: Filter results by the link's expiry date. Send a value in **YYYY-MM-DD** format. schema: *ref_389 examples: *ref_390 paymentLinkId: name: paymentLinkId in: path description: Unique identifier that we assigned to the payment link. required: true schema: *ref_99 examples: *ref_100 paymentPlanId: name: paymentPlanId in: path description: Unique identifier that the merchant assigned to the payment plan. required: true schema: *ref_117 examples: *ref_118 customerName: name: customerName in: query description: Filter by the customer's name. schema: *ref_391 examples: *ref_392 last4: name: last4 in: query description: Filter by the last four digits of the card or account number. schema: *ref_393 examples: *ref_394 paymentPlan: name: paymentPlan in: query description: Filter by the name of the payment plan. schema: *ref_395 examples: *ref_396 frequency: name: frequency in: query description: Filter by the frequency of subscription payments. schema: *ref_397 examples: *ref_398 status: name: status in: query description: Filter by the current status of the subscription. schema: *ref_399 examples: *ref_400 endDate: name: endDate in: query description: | Format: `YYYY-MM-DD` Filter subscriptions that end on a specific date. schema: *ref_401 examples: *ref_402 nextDueDate: name: nextDueDate in: query description: | Format: `YYYY-MM-DD` Filter subscriptions by the date that the next payment is collected. schema: *ref_403 examples: *ref_404 subscriptionId: name: subscriptionId in: path description: Unique identifier that the merchant assigned to the subscription. required: true schema: *ref_135 examples: *ref_136 secureTokenIdInQuery: name: secureTokenId in: query description: Unique identifier that the merchant assigned to the secure token. schema: *ref_405 examples: *ref_406 phone: name: phone in: query description: Filter by the customer's phone number. schema: *ref_407 examples: *ref_408 email: name: email in: query description: Filter by the customer's email address. schema: *ref_409 examples: *ref_410 token: name: token in: query description: Filter by the token that the merchant used in a transaction to represent the customer's payment details. schema: *ref_411 examples: *ref_412 first6: name: first6 in: query description: Filter by the first six digits of the card number. schema: *ref_413 examples: *ref_414 secureTokenIdInPath: name: secureTokenId in: path required: true description: Unique identifier that the merchant assigned to the secure token. schema: *ref_161 examples: *ref_162 processingTerminalId: name: processingTerminalId in: path required: true description: Unique identifier that our gateway assigned to the terminal. schema: *ref_415 examples: *ref_416 processingTerminalIdQuery: name: processingTerminalId in: query description: Filter by terminal ID. schema: *ref_235 examples: *ref_236 orderId: name: orderId in: query description: Filter payments by order ID. schema: *ref_417 examples: *ref_418 operator: name: operator in: query description: Filter payments by operator. schema: *ref_419 examples: *ref_420 cardholderName: name: cardholderName in: query description: Filter payments by the cardholder’s name. schema: *ref_421 examples: *ref_422 parameters-first6: name: first6 in: query description: Filter payments by the first six digits of the card number that the customer used in the transaction. schema: *ref_423 examples: *ref_424 parameters-last4: name: last4 in: query description: Filter payments by the last four digits of the card number that the customer used in the transaction. schema: *ref_425 examples: *ref_426 tender: name: tender in: query description: Filter by tender type. schema: *ref_427 examples: *ref_428 tipMode: name: tipMode in: query description: Filter payments by tip. schema: *ref_429 examples: *ref_430 type: name: type in: query description: Filter payments by transaction type. schema: *ref_431 examples: *ref_432 parameters-status: name: status in: query description: Filter payments by the status of the transaction. schema: *ref_433 examples: *ref_434 components-parameters-dateFrom: name: dateFrom in: query description: Filter by payments that the processor processed after a specific date. The date format follows the ISO 8601 standard. schema: *ref_435 examples: *ref_436 components-parameters-dateTo: name: dateTo in: query description: Filter by payments that the processer processed before a specific date. The date format follows the ISO 8601 standard. schema: *ref_437 examples: *ref_438 settlementState: name: settlementState in: query description: Filter payments by the settlement status of the transaction. schema: *ref_439 examples: *ref_440 settlementDate: name: settlementDate in: query description: Filter by payments that the processor settled on a specific date in the format **YYYY-MM-DD**. schema: *ref_441 examples: *ref_442 parameters-paymentLinkId: name: paymentLinkId in: query description: Unique identifier that our gateway assigned to the payment link. schema: *ref_443 examples: *ref_444 paymentId: name: paymentId in: path required: true description: Unique identifier of the payment that the merchant wants to retrieve. schema: *ref_209 examples: *ref_210 serialNumber: name: serialNumber description: Serial number of the merchant’s payment device. in: path required: true schema: *ref_445 examples: *ref_446 paymentInstructionId: name: paymentInstructionId description: Unique identifier that we assigned to the payment instruction. in: path required: true schema: *ref_225 examples: *ref_226 parameters-orderId: name: orderId in: query description: Filter refunds by the unique identifier that the merchant assigned to the order. schema: *ref_447 examples: *ref_448 parameters-operator: name: operator in: query description: Filter refunds by the operator who initiated the request. schema: *ref_449 examples: *ref_450 parameters-cardholderName: name: cardholderName in: query description: Filter refunds by cardholder name. schema: *ref_451 examples: *ref_452 components-parameters-first6: name: first6 in: query description: Filter refunds by the first six digits of the card number. schema: *ref_453 examples: *ref_454 components-parameters-last4: name: last4 in: query description: Filter refunds by the last four digits of the card number. schema: *ref_455 examples: *ref_456 components-parameters-status: name: status in: query description: Filter refunds by the current status of the refund. schema: *ref_457 examples: *ref_458 parameters-v1_components-parameters-dateFrom: name: dateFrom in: query description: Filter by refunds processed after a specific date. The date format follows the ISO 8601 standard. schema: *ref_459 examples: *ref_460 parameters-v1_components-parameters-dateTo: name: dateTo in: query description: Filter by refunds processed before a specific date. The date format follows the ISO 8601 standard. schema: *ref_461 examples: *ref_462 parameters-settlementState: name: settlementState in: query description: Status of the settlement. schema: *ref_463 examples: *ref_464 parameters-settlementDate: name: settlementDate in: query description: Date the transaction was settled. schema: *ref_465 examples: *ref_466 refundId: name: refundId description: Unique identifier that our gateway assigned to the refund. in: path required: true schema: *ref_240 examples: *ref_241 parameters-serialNumber: name: serialNumber description: Serial number that identifies the merchant’s payment device. in: path required: true schema: *ref_467 examples: *ref_468 refundInstructionId: name: refundInstructionId description: Unique identifier that we assigned to the refund instruction. in: path required: true schema: *ref_250 examples: *ref_251 signatureInstructionId: name: signatureInstructionId description: Unique identifier that our gateway assigned to the signature instruction. in: path required: true schema: *ref_254 examples: *ref_255 signatureId: name: signatureId in: path description: Unique identifier that we assigned to the signature. required: true schema: *ref_469 examples: *ref_470 bankTransferPaymentsProcessingTerminalId: name: processingTerminalId in: query required: true description: Filter results by the unique identifier that we assigned to the terminal. schema: *ref_471 examples: *ref_472 bankTransferPaymentsOrderId: name: orderId in: query description: Filter results by the order ID of the payment. schema: *ref_473 examples: *ref_474 bankTransferPaymentsNameOnAccount: name: nameOnAccount in: query description: Filter results by the account holder's name. schema: *ref_475 examples: *ref_476 bankTransferPaymentsLast4: name: last4 in: query description: Filter results by the last four digits of the account number. schema: *ref_477 examples: *ref_478 bankTransferPaymentsType: name: type in: query description: Filter results by transaction type. schema: *ref_479 examples: *ref_480 bankTransferPaymentsStatus: name: status in: query description: Filter results by the status of the payment. schema: *ref_481 examples: *ref_482 bankTransferPaymentsDateFrom: name: dateFrom in: query description: Filter results by payments that the merchant ran after a specific date. The value follows the [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) standard. schema: *ref_483 examples: *ref_484 bankTransferPaymentsDateTo: name: dateTo in: query description: Filter results by payments that the merchant ran before a specific date. The value follows the [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) standard. schema: *ref_485 examples: *ref_486 bankTransferPaymentsSettlementState: name: settlementState in: query description: Filter results by the settlement status. schema: *ref_487 examples: *ref_488 bankTransferPaymentsSettlementDate: name: settlementDate in: query description: Filter results by the settlement date. Send a value in **YYYY-MM-DD** format. schema: *ref_489 examples: *ref_490 components-parameters-paymentLinkId: name: paymentLinkId in: query description: Filter results by the paymentLinkId. schema: *ref_491 examples: *ref_492 bankTransferPaymentsPaymentId: name: paymentId description: Unique identifier that our gateway assigned to the payment. in: path required: true schema: *ref_272 examples: *ref_273 bankTransferRefundProcessingTerminalId: name: processingTerminalId in: query required: true description: Filter results by the unique identifier that we assigned to the terminal. schema: *ref_493 examples: *ref_494 bankTransferRefundOrderId: name: orderId in: query description: Filter results by the order ID of the refund. schema: *ref_495 examples: *ref_496 bankTransferRefundNameOnAccount: name: nameOnAccount in: query description: Filter results by the accountholder's name. schema: *ref_497 examples: *ref_498 bankTransferRefundLast4: name: last4 in: query description: Filter results by the last four digits of the account number. schema: *ref_499 examples: *ref_500 bankTransferRefundType: name: type description: Filter results by transaction type. in: query schema: *ref_501 examples: *ref_502 bankTransferRefundStatus: name: status in: query description: Filter results by the status of the refund. schema: *ref_503 examples: *ref_504 bankTransferRefundDateFrom: name: dateFrom in: query description: Filter results by refunds that the merchant ran after a specific date. The value follows the [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) standard. schema: *ref_505 examples: *ref_506 bankTransferRefundDateTo: name: dateTo in: query description: Filter results by refunds that the merchant ran before a specific date. The value follows the [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) standard. schema: *ref_507 examples: *ref_508 bankTransferRefundSettlementState: name: settlementState in: query description: Filter results by the settlement status. schema: *ref_509 examples: *ref_510 bankTransferRefundSettlementDate: name: settlementDate in: query description: Filter results by the settlement date. Send a value in **YYYY-MM-DD** format. schema: *ref_511 examples: *ref_512 bankTransferRefundRefundId: name: refundId description: Unique identifier that our gateway assigned to the refund. in: path required: true schema: *ref_285 examples: *ref_286 merchantPlatformId: name: merchantPlatformId in: path description: Unique identifier of the merchant platform that we sent to you when you created the merchant platform. required: true schema: *ref_297 examples: *ref_298 includeClosed: name: includeClosed in: query description: | Indicates if you want to return closed processing accounts. This includes processing accounts that have a status of `terminated`, `cancelled`, or `rejected`. **Note**: By default, we return only open processing accounts. schema: *ref_513 examples: *ref_514 processingAccountId: name: processingAccountId in: path description: Unique identifier that we assigned to the processing account. required: true schema: *ref_311 examples: *ref_312 processing-accounts-v1_components-parameters-status: name: status in: query schema: *ref_515 fromDateTime: name: fromDateTime in: query schema: *ref_516 toDateTime: name: toDateTime in: query schema: *ref_517 contactId: name: contactId in: path description: Unique identifier for the contact. required: true schema: *ref_346 examples: *ref_347 parameters-v1_components-parameters-status: name: status in: query description: Filter event subscriptions by subscription status. schema: *ref_518 examples: *ref_519 event: name: event in: query description: Filter event subscriptions by an event type. For a list of event types, go to [Events List](https://docs.payroc.com/knowledge/events/events-list). schema: *ref_520 examples: *ref_521 parameters-subscriptionId: name: subscriptionId in: path description: | Unique identifier that we assigned to the event subscription. **Note:** Our gateway returned the subscriptionId in the id field in the response of the [Create Event Subscription](https://docs.payroc.com/api/schema/notifications/event-subscriptions/create) method. required: true schema: *ref_522 examples: *ref_523 terminalOrderId: name: terminalOrderId in: path description: Unique identifier of the terminal order. required: true schema: *ref_524 examples: *ref_525 achDepositId: name: achDepositId description: Unique identifier of the ACH deposit. in: path required: true schema: *ref_526 examples: *ref_527 achDepositIdQuery: name: achDepositId description: Unique identifier of the ACH deposit. You must provide either the 'achDepositId' or the 'date'. in: query schema: *ref_528 examples: *ref_529 attachmentId: name: attachmentId in: path description: Unique identifier of the attachment required: true schema: *ref_530 example: '12876' schemas: '400': type: object properties: *ref_9 required: *ref_10 '401': type: object properties: *ref_531 required: *ref_532 '403': type: object properties: *ref_533 required: *ref_534 '404': type: object properties: *ref_338 required: *ref_339 '406': type: object properties: *ref_535 required: *ref_536 '409': type: object properties: *ref_27 required: *ref_28 '413': type: object properties: *ref_537 required: *ref_538 '415': type: object properties: *ref_539 required: *ref_540 '500': type: object properties: *ref_541 required: *ref_542 link: type: object readOnly: true description: Object that contains HATEOAS links for the resource. properties: *ref_4 required: *ref_5 example: *ref_6 paginatedList: type: object description: Contains the pagination properties that you use to navigate through a list of results. properties: *ref_38 address: required: *ref_0 type: object title: address description: Object that contains information about the address. properties: *ref_1 contactMethodEmail: required: *ref_543 type: object title: email properties: *ref_544 contactMethodPhone: required: *ref_545 type: object title: phone properties: *ref_546 contactMethodMobile: required: *ref_547 type: object title: mobile properties: *ref_548 contactMethodFax: required: *ref_549 type: object title: fax properties: *ref_550 contactMethod: discriminator: *ref_2 oneOf: *ref_3 fundingRecipient: required: *ref_7 type: object title: funding recipient properties: *ref_8 paginatedFundRecipients: type: object title: paginated funding recipients allOf: *ref_551 identifier: required: *ref_289 type: object title: identifier properties: *ref_290 ownerRelationship: required: *ref_552 type: object title: Owner relationship description: Object that contains information about the owner's relationship to the business. properties: *ref_553 owner: type: object title: owner required: *ref_30 properties: *ref_31 PaymentMethodAch: type: object title: ACH payment method properties: *ref_554 paymentMethods: uniqueItems: true type: array description: Array of PaymentMethodAch objects. items: *ref_555 example: *ref_556 fundingAccount: required: *ref_20 type: object title: funding account properties: *ref_21 createFundingRecipient: required: *ref_557 type: object title: create funding recipient properties: *ref_558 listFundingAccounts: type: object title: paginated funding accounts allOf: *ref_559 baseIntent: type: object title: base pricing intent description: Object that contains information about the base fees. properties: *ref_560 required: *ref_561 baseUsMonthly: type: object title: monthly required: *ref_562 properties: *ref_563 baseUsAnnual: type: object title: annual required: *ref_564 properties: *ref_565 baseUs: type: object title: US base fees description: Object that contains information about U.S. base fees. properties: *ref_315 required: *ref_316 percentage: description: Percentage value up to 2 decimal places. title: percentage type: number format: double minimum: 0 maximum: 100 example: 1.25 amount: type: integer minimum: 0 processorFee: type: object title: Processor Fee description: Object that contains information about the processor fees. properties: *ref_43 interchangePlusAmexOptBlue: type: object title: optBlue required: *ref_566 properties: *ref_567 interchangePlusAmexDirect: type: object title: direct required: *ref_568 properties: *ref_569 pinDebit: type: object description: Object that contains the fees for PIN-debit transactions. required: *ref_44 properties: *ref_45 electronicBenefitsTransfer: type: object description: Object that contains the fees for EBT transactions. required: *ref_46 properties: *ref_47 enhancedInterchange: type: object description: Object that contains the fees for enhanced interchange services. required: *ref_48 properties: *ref_49 specialityCards: type: object description: Object that contains the fees for speciality cards. required: *ref_50 properties: *ref_51 interchangePlus: type: object title: Interchange Plus Plan description: Object that contains information about Interchange Plus. properties: *ref_317 required: *ref_318 qualRates: type: object required: *ref_52 properties: *ref_53 interchangePlusPlusAmexOptBlue: type: object title: optBlue required: *ref_570 properties: *ref_571 interchangePlusPlusAmexDirect: type: object title: direct required: *ref_572 properties: *ref_573 interchangePlusPlus: type: object title: Interchange Plus Plus description: Object that contains information about Interchange Plus Plus. properties: *ref_574 required: *ref_575 tiered3AmexOptBlue: type: object title: optBlue required: *ref_576 properties: *ref_577 tiered3AmexDirect: type: object title: direct required: *ref_578 properties: *ref_579 tiered3: type: object title: Tiered pricing with three tiers description: Object that contains information about tiered pricing with three tiers. properties: *ref_319 required: *ref_320 qualRatesWithPremium: type: object allOf: *ref_54 tiered4AmexOptBlue: type: object title: optBlue required: *ref_580 properties: *ref_581 tiered4AmexDirect: type: object title: direct required: *ref_582 properties: *ref_583 tiered4: type: object title: Tiered pricing with four tiers description: Object that contains information about tiered pricing with four tiers. properties: *ref_321 required: *ref_322 qualRatesWithPremiumAndRegulated: type: object allOf: *ref_584 tiered6AmexOptBlue: type: object title: optBlue required: *ref_585 properties: *ref_586 tiered6AmexDirect: type: object title: direct required: *ref_587 properties: *ref_588 tiered6: type: object title: Tiered pricing with six tiers description: Object that contains information about tiered pricing with six tiers. properties: *ref_323 required: *ref_324 flatRateAmexDirect: type: object title: direct required: *ref_589 properties: *ref_590 flatRate: type: object title: Flat Rate Plan description: Object that contains information about Flat Rate. properties: *ref_325 required: *ref_326 consumerChoice: type: object title: Consumer Choice Plan description: Object that contains information about ConsumerChoice. properties: *ref_327 required: *ref_328 rewardPayChoice: type: object title: RewardPayChoice Plan description: Object that contains information about RewardPayChoice. properties: *ref_329 required: *ref_330 ach: type: object description: Object that contains the fees for ACH transactions. properties: *ref_331 gatewayUs5.0: type: object description: Object that contains information about the gateway fees for MPA 5.0. title: gateway fees properties: *ref_591 required: *ref_592 hardwareAdvantagePlan: type: object description: Object that contains information about the Hardware Advantage Plan. properties: *ref_593 required: *ref_594 serviceUs5.0: title: hardwareAdvantagePlan type: object description: Object that contains information about the Hardware Advantage Plan. discriminator: *ref_595 oneOf: *ref_596 servicesUs5.0: title: US version 5.0 services array description: Array of polymorphic objects that contain information about additional services that we offer. type: array items: *ref_597 uniqueItems: true pricingAgreementUs5.0: type: object title: US pricing agreement version 5.0 description: Object that contains information about U.S. pricing intents for Merchant Processing Agreement (MPA) 5.0. required: *ref_287 properties: *ref_288 pricingIntent5.0: type: object title: '5.0' description: Object that contains information about a pricing intent for Merchant Processing Agreement (MPA) 5.0. allOf: *ref_598 pricingIntent: type: object title: pricing intent description: Polymorphic object that contains pricing intent information. oneOf: *ref_56 paginatedPricingIntent: type: object title: paginated pricing intents description: Object that contains information about your pricing intents. allOf: *ref_599 patchAdd: type: object title: Patch Add Operation description: A Patch Add Operation. required: *ref_600 properties: *ref_601 patchRemove: type: object title: Patch Remove Operation description: A Patch Remove Operation. required: *ref_602 properties: *ref_603 patchReplace: type: object title: Patch Replace Operation description: A Patch Replace Operation. required: *ref_604 properties: *ref_605 patchMove: type: object title: Patch Move Operation description: A Patch Move Operation. required: *ref_606 properties: *ref_607 patchCopy: type: object title: Patch Copy Operation description: A Patch Copy Operation. required: *ref_608 properties: *ref_609 patchTest: type: object title: Patch Test Operation description: A Patch Test Operation. required: *ref_610 properties: *ref_611 patchDocument: title: Patch Operation description: A JSON Patch operation as defined by RFC 6902. discriminator: *ref_612 oneOf: *ref_613 patchRequest: type: array description: A JSON Patch document as defined by RFC 6902. items: *ref_101 example: *ref_102 instruction: type: object description: Inform the payfac what to do with the specified funds. ** title: funding instruction properties: *ref_58 merchantBalance: type: object description: Object that contains information about the total funds available to the merchant. title: merchant balance properties: *ref_614 activityRecord: type: object description: Array of activityRecord objects. title: activity record properties: *ref_615 required: *ref_616 merchantSummary: type: object title: merchant summary description: Object that contains information about the merchant. properties: *ref_68 example: *ref_69 batch: type: object title: batch properties: *ref_66 settledSummary: type: object title: settlement summary description: Object that contains information about the settlement. properties: *ref_617 example: *ref_618 batchSummary: type: *ref_77 title: batch summary description: Object that contains information about the batch. If we can't match a dispute to a batch, we don't return 'batch' object. properties: *ref_78 cardSummary: type: object title: card summary description: Object that contains information about the card. properties: *ref_79 authorizationSummary: type: object title: authorization summary description: Object that contains information about the authorization. properties: *ref_619 transaction: type: object title: transaction description: Object that contains information about the transaction. properties: *ref_72 transactionSummary: type: object title: transaction summary description: Object that contains summary information about the transaction that the dispute is linked to. properties: *ref_81 authorization: type: object title: authorization description: Object that contains information about the authorization. properties: *ref_80 disputeStatus: type: object title: dispute status description: Object that contains information about the current status of the dispute. properties: *ref_82 dispute: type: object title: dispute description: Object that contains information about the dispute. properties: *ref_620 currency: type: string description: Currency of the transaction. The value for the currency follows the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard. enum: *ref_83 promptPaymentLinkCharge: required: *ref_84 type: object title: prompt description: Object that contains information about the charge when the customer enters the amount of the transaction. properties: *ref_85 presetPaymentLinkCharge: required: *ref_86 type: object title: preset description: Object that contains information about the charge when the merchant enters the amount of the transaction. properties: *ref_87 multiUsePaymentLinkOrder: required: *ref_621 type: object description: Object that contains information about the order. properties: *ref_622 customLabel: type: object description: Object that contains the information for the custom label. properties: *ref_88 paymentLinkAssets: required: *ref_89 type: object readOnly: true description: Object that contains shareable assets for the payment link. properties: *ref_90 credentialOnFile: type: object description: Object that contains information about saving the customer’s payment details. properties: *ref_91 multiUsePaymentLink: required: *ref_92 type: object title: multiUse description: Object that contains information about a multi-use payment link. properties: *ref_93 singleUsePaymentLinkOrder: required: *ref_623 type: object description: Object that contains information about the order. properties: *ref_624 singleUsePaymentLink: required: *ref_94 type: object title: singleUse description: Object that contains information about a single-use payment link. properties: *ref_95 paymentLinkPaginatedList: required: *ref_625 type: object allOf: *ref_626 paymentLinkEmailRecipient: required: *ref_627 type: object description: Object that contains the contact details of the recipient. properties: *ref_628 paymentLinkEmailShareEvent: required: *ref_106 type: object title: email description: Object that contains the information about a sharing event that the merchant sent by email. properties: *ref_107 sharingEventPaginatedList: required: *ref_629 type: object allOf: *ref_630 paymentPlanBase: required: *ref_631 type: object properties: *ref_632 paymentPlanSetupOrderBase: type: object description: Object that contains information about the initial cost that a customer pays to set up the subscription. properties: *ref_633 paymentPlanOrderBreakdownBase: required: *ref_634 type: object description: | Object that contains information about the taxes that apply to the transaction. properties: *ref_635 retrievedTax: required: *ref_124 type: object properties: *ref_125 paymentPlanOrderBreakdown: required: *ref_112 type: object allOf: *ref_113 paymentPlanSetupOrder: type: object allOf: *ref_636 paymentPlanRecurringOrderBase: type: object description: | Object that contains information about the cost of each payment. **Note:** Send this object only if the value for **type** is `automatic`. properties: *ref_637 paymentPlanRecurringOrder: type: object allOf: *ref_638 paymentPlan: required: *ref_114 type: object allOf: *ref_115 paymentPlanPaginatedList: required: *ref_639 type: object allOf: *ref_640 paymentPlanSummary: required: *ref_641 type: object properties: *ref_642 secureTokenSummary: required: *ref_138 type: object description: Object that contains information about the secure token. properties: *ref_139 subscriptionPaymentOrderBase: description: Object that contains information about the initial cost that a customer pays to set up the subscription. type: object properties: *ref_121 convenienceFee: required: *ref_172 type: object readOnly: true description: Object that contains information about the convenience fee for the transaction. properties: *ref_173 subscriptionOrderBreakdownBase: required: *ref_122 type: object properties: *ref_123 surcharge: type: object description: | Object that contains information about the surcharge. properties: *ref_169 subscriptionOrderBreakdown: required: *ref_127 type: object description: | Object that contains information about the surcharge and taxes that apply to the transaction. allOf: *ref_128 subscriptionPaymentOrder: type: object allOf: *ref_137 subscriptionRecurringOrderBase: type: object properties: *ref_126 subscriptionRecurringOrder: type: object description: | Object that contains information about the cost of each payment. allOf: *ref_643 subscriptionState: required: *ref_140 type: object description: A snapshot of the subscription's current state. properties: *ref_141 customField: required: *ref_129 type: object properties: *ref_130 subscription: required: *ref_131 type: object properties: *ref_132 subscriptionPaginatedList: required: *ref_644 type: object allOf: *ref_645 secureTokenPayload: required: *ref_179 type: object writeOnly: true title: secureToken description: Object that contains information about the secure token that represents the customer’s payment details. properties: *ref_180 taxRate: type: object required: *ref_170 properties: *ref_171 subscriptionOrderBreakdownRequest: required: *ref_119 type: object description: | Object that contains information about the taxes to apply to the transaction. allOf: *ref_120 subscriptionPaymentOrderRequest: type: object allOf: *ref_646 subscriptionRecurringOrderRequest: type: object description: | Object that contains information about the cost of each payment. **Note:** Send this object only if the value for **type** is `automatic`. allOf: *ref_647 subscriptionRequest: required: *ref_648 type: object properties: *ref_649 subscriptionPaymentRequest: required: *ref_650 properties: *ref_651 paymentSummary: required: *ref_233 type: object description: Object that contains information about a payment. properties: *ref_234 subscriptionPayment: required: *ref_652 type: object properties: *ref_653 retrievedAddress: type: object title: address description: Object that contains information about the address. properties: *ref_150 retrievedShipping: description: Object that contains information about the customer and their shipping address. type: object properties: *ref_654 retrievedCustomer: type: object description: Object that contains the customer's contact details and address information. properties: *ref_193 achSource: required: *ref_153 type: object title: ach description: Object that contains the customer's account details. properties: *ref_154 padSource: required: *ref_155 type: object title: pad description: Object that contains the customer's account details. properties: *ref_156 surcharging: required: *ref_260 type: object description: Object that contains surcharge information. Our gateway returns this object only if the merchant adds a surcharge to transactions. properties: *ref_261 cardSource: required: *ref_157 type: object title: Card description: Object that contains the customer's card details. properties: *ref_158 secureToken: required: *ref_151 type: object description: Object that contains information about the secure token. properties: *ref_152 achSourceWithAccountType: allOf: *ref_655 padSourceWithAccountType: allOf: *ref_656 secureTokenWithAccountType: allOf: *ref_159 secureTokenPaginatedListWithAccountType: required: *ref_657 type: object allOf: *ref_658 shipping: description: Object that contains information about the customer and their shipping address. type: object properties: *ref_213 customer: type: object description: Object that contains the customer's contact details and address information. properties: *ref_176 ipAddress: required: *ref_177 type: object writeOnly: true description: Object that contains the IP address of the device that sent the request. properties: *ref_178 achPayload: required: *ref_163 type: object writeOnly: true title: ach description: Object that contains information about the payment details for the customer’s automated clearing house (ACH) transactions. properties: *ref_164 padPayload: required: *ref_165 type: object writeOnly: true title: pad description: Object that contains information about the payment details for the customer’s preauthorized electronic debit (PAD) transactions. properties: *ref_166 deviceConfig: required: *ref_659 type: object description: Object that contains information about the configuration of the POS terminal. properties: *ref_660 device: required: *ref_142 type: object description: Object that contains information about the physical device the merchant used to capture the customer’s card details. properties: *ref_143 rawCardDetails: required: *ref_661 type: object title: raw description: Object that contains information about the unencrypted card details. properties: *ref_662 encryptionCapableDevice: required: *ref_144 type: object description: Object that contains information about the encryption details of the POS terminal. allOf: *ref_145 ebtDetails: type: object required: *ref_221 description: Object that contains information about the Electronic Benefit Transfer (EBT) transaction. properties: *ref_222 voucher: required: *ref_663 type: object description: | Object that contains information about the EBT voucher. **Note:** Vouchers are available only for EBT SNAP payments. properties: *ref_664 ebtDetailsWithVoucher: type: object required: *ref_146 description: Object that contains information about the Electronic Benefit Transfer (EBT) transaction. allOf: *ref_147 iccCardDetails: required: *ref_665 type: object title: icc description: Object that contains information about the Integrated Circuit Card (ICC). properties: *ref_666 fullyEncryptedKeyedDataFormat: required: *ref_667 type: object title: fullyEncrypted description: Object that contains information about the encrypted card data for keyed transactions. properties: *ref_668 partiallyEncryptedKeyedDataFormat: required: *ref_669 type: object title: partiallyEncrypted description: Object that contains information about the partially-encrypted card data for keyed transactions. properties: *ref_670 plainTextKeyedDataFormat: required: *ref_671 type: object title: plainText description: Object that contains information about the plain-text card data for keyed transactions. properties: *ref_672 dukptPinDetails: required: *ref_148 type: object title: dukpt description: Object that contains information about encrypted PIN details. properties: *ref_149 keyedCardDetails: required: *ref_673 type: object title: keyed description: Object that contains information about the keyed card details. properties: *ref_674 encryptedSwipedDataFormat: required: *ref_675 type: object title: encrypted description: Object that contains information about the encrypted swiped card data. properties: *ref_676 plainTextSwipedDataFormat: required: *ref_677 type: object title: plainText description: Object that contains information about plain-text swiped card data. properties: *ref_678 swipedCardDetails: required: *ref_679 type: object title: swiped description: Object that contains information about the customer’s card details for swiped transactions. properties: *ref_680 cardPayload: required: *ref_167 type: object writeOnly: true title: card description: Object that contains information about the customer’s payment card. properties: *ref_168 rawPinDetails: required: *ref_681 type: object title: raw description: Object that contains information about the unencrypted PIN details. properties: *ref_682 singleUseTokenPayload: required: *ref_181 type: object writeOnly: true title: singleUseToken description: Object that contains information about the single-use token, which represents the customer’s payment details. properties: *ref_182 gatewayThreeDSecure: required: *ref_183 type: object title: gateway description: Object that contains the 3-D Secure information from our gateway. properties: *ref_184 thirdPartyThreeDSecure: required: *ref_185 type: object title: thirdParty description: Object that contains the 3-D Secure information from a third party. properties: *ref_186 tokenizationRequest: required: *ref_683 type: object properties: *ref_684 singleUseTokenAccountUpdate: required: *ref_685 type: object description: Object that contains the token. properties: *ref_686 accountUpdate: description: Polymorphic object that contains information about the single-use token. discriminator: *ref_687 oneOf: *ref_688 singleUseTokenRequest: required: *ref_689 type: object properties: *ref_690 singleUseToken: required: *ref_691 type: object properties: *ref_692 hostedFieldsCreateSessionRequest: required: *ref_693 type: object title: Hosted Fields Initialization description: Object that contains information about Hosted Fields initialization request. properties: *ref_694 hostedFieldsCreateSessionResponse: required: *ref_695 type: object properties: *ref_696 applePaySessions: required: *ref_697 type: object properties: *ref_698 applePayResponseSession: required: *ref_699 type: object properties: *ref_700 order: required: *ref_218 type: object description: Object that contains details about the transaction. properties: *ref_219 dccOffer: required: *ref_227 type: object 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). properties: *ref_228 firstTxnReferenceData: type: object description: Object that contains information about the initial payment for the payment instruction. properties: *ref_701 standingInstructions: required: *ref_702 type: object description: If you don't use our Subscriptions mechanism, include this section to configure your standing/recurring orders. properties: *ref_703 paymentOrderBase: required: *ref_187 type: object description: Object that contains information about the payment. allOf: *ref_188 tip: required: *ref_211 type: object description: Object that contains information about the tip. properties: *ref_212 choiceRate: required: *ref_704 type: object description: | Object that contains information about the choice rate. We return this only if the value for offered was `true`. readOnly: true properties: *ref_705 dualPricing: required: *ref_706 type: object description: Object that contains information about dual pricing. properties: *ref_707 breakdownBase: required: *ref_189 type: object description: Object that contains information about the breakdown of the transaction. properties: *ref_190 breakdown: type: object allOf: *ref_708 unitOfMeasure: type: string 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). example: QAN enum: *ref_709 lineItemBase: required: *ref_191 type: object description: List of line items. properties: *ref_192 lineItem: type: object allOf: *ref_710 itemizedBreakdown: required: *ref_711 type: object description: Object that contains information about the breakdown of the transaction. allOf: *ref_712 paymentOrder: type: object description: Object that contains information about the payment. allOf: *ref_194 securityCheck: type: object description: Object that contains information about card verification and security checks. properties: *ref_195 emvTag: required: *ref_196 type: object description: Object that contains information about the EMV tag. properties: *ref_197 cardBalance: required: *ref_198 type: object description: Object that contains information about the total funds available in the card. properties: *ref_199 retrievedCard: required: *ref_231 type: object description: Object that contains the details of the payment card. properties: *ref_232 refundSummary: required: *ref_200 type: object description: Object that contains information about a refund. properties: *ref_201 supportedOperations: type: array items: *ref_202 description: | Array of operations that you can perform on the transaction. - `capture` - Capture the payment. - `refund` - Refund the payment. - `fullyReverse` - Fully reverse the transaction. - `partiallyReverse` - Partially reverse the payment. - `incrementAuthorization` - Increase the amount of the authorization. - `adjustTip` - Adjust the tip post-payment. - `addSignature` - Add a signature to the payment. - `setAsReady` - Set the transaction’s status to `ready`. - `setAsPending` - Set the transaction’s status to `pending`. example: *ref_203 transactionResult: required: *ref_204 type: object properties: *ref_205 description: Object that contains information about the transaction response details. retrievedPayment: required: *ref_206 type: object properties: *ref_207 paymentPaginatedListForRead: required: *ref_713 type: object allOf: *ref_714 taxAmount: type: object required: *ref_715 properties: *ref_716 tax: type: object description: "Polymorphic object that contains tax details. \n\nThe value of the type parameter determines which variant you should use: \n-\t`amount` - Tax is a fixed amount.\n-\t`rate` - Tax is a percentage.\n" discriminator: *ref_174 oneOf: *ref_175 breakdownRequest: type: object allOf: *ref_717 lineItemRequest: type: object allOf: *ref_718 itemizedBreakdownRequest: required: *ref_216 type: object description: Object that contains information about the breakdown of the transaction. allOf: *ref_217 paymentOrderRequest: type: object description: Object that contains information about the payment. allOf: *ref_719 digitalWalletPayload: required: *ref_258 type: object writeOnly: true title: digitalWallet description: Object that contains information about the payment details in the customer’s digital wallet. properties: *ref_259 schemas-credentialOnFile: type: object description: Object that contains information about saving the customer’s payment details. properties: *ref_220 offlineProcessing: required: *ref_720 type: object description: Object that contains information about the transaction if the merchant ran it when the terminal was offline. properties: *ref_721 paymentRequest: required: *ref_722 type: object properties: *ref_723 card: required: *ref_256 type: object description: Object that contains the details of the payment card. properties: *ref_257 payment: required: *ref_214 type: object properties: *ref_215 breakdownAdjustment: type: object description: Object that contains information about the tip amount of a transaction. properties: *ref_724 orderAdjustment: required: *ref_725 type: object title: order description: Object that contains information about the adjustment to the transaction. Send this object if the merchant is adjusting the order details. properties: *ref_726 statusAdjustment: required: *ref_242 type: object title: status description: Object that contains information about the adjustment to the transaction. Send this object if the merchant is adjusting the status of the transaction. properties: *ref_243 customerAdjustment: required: *ref_244 type: object title: customer description: Object that contains information about the adjustment to the transaction. Send this object if the merchant is adjusting the customer’s contact details. properties: *ref_245 signatureAdjustment: required: *ref_727 type: object title: signature description: | Object that contains the signature for the transaction. **Note:** If the merchant previously added a signature to the transaction, they can’t adjust or delete the signature. properties: *ref_728 paymentAdjustment: required: *ref_729 type: object description: Object that contains the transaction adjustment object. properties: *ref_730 paymentCapture: description: Object that contains the details of the payment that the merchant wants to capture. type: object properties: *ref_731 paymentReversal: type: object properties: *ref_732 referencedRefund: description: Object that contains the details of the payment that the merchant wants to refund. required: *ref_733 type: object properties: *ref_734 breakdownForPaymentInstructions: type: object allOf: *ref_735 paymentInstructionOrder: required: *ref_736 type: object description: Object that contains information about the payment. allOf: *ref_737 customizationOptions: type: object description: Object that contains available options to customize certain aspects of an instruction. properties: *ref_246 paymentInstructionRequest: required: *ref_738 type: object description: Object that contains the instructions for initiating a payment on a physical device. properties: *ref_739 deviceInstruction: type: object description: Object that contains information about the status of the instruction properties: *ref_247 paymentInstruction: required: *ref_223 type: object allOf: *ref_224 refundOrder: required: *ref_229 type: object description: Object that contains information about the refund. allOf: *ref_230 retrievedRefund: required: *ref_237 type: object description: Object that contains information about the retrieved refund. properties: *ref_238 refundPaginatedList: required: *ref_740 type: object description: Object that contains information about refund objects. allOf: *ref_741 unreferencedRefund: required: *ref_742 type: object description: Refund a payment that is not linked to a previous transaction. Unreferenced refunds are available only on certain accounts. properties: *ref_743 refundAdjustment: required: *ref_744 type: object description: Object that contains information about the adjustment to the refund. properties: *ref_745 refundInstructionOrder: required: *ref_746 type: object description: Object that contains information about the refund. allOf: *ref_747 refundInstructionRequest: required: *ref_748 type: object description: Object that contains information about the instruction request to initiate a refund on a payment device. properties: *ref_749 refundInstruction: required: *ref_248 type: object allOf: *ref_249 signatureInstructionRequest: required: *ref_750 type: object description: Object that contains the instructions for capturing a signature on a physical device. properties: *ref_751 signatureInstruction: required: *ref_252 type: object allOf: *ref_253 cardVerificationRequest: required: *ref_752 type: object properties: *ref_753 cardVerificationResult: required: *ref_754 type: object properties: *ref_755 balanceInquiry: required: *ref_756 type: object properties: *ref_757 balance: required: *ref_758 type: object properties: *ref_759 cardBinPayload: required: *ref_760 type: object writeOnly: true title: cardBin description: Object that contains information about the card's bank identification number (BIN). properties: *ref_761 binLookup: required: *ref_762 type: object properties: *ref_763 cardInfo: required: *ref_262 type: object readOnly: true properties: *ref_263 description: Object that contains information about the card. fxRateInquiry: required: *ref_764 type: object properties: *ref_765 fxRateInquiryResult: required: *ref_766 type: object description: Object that indicates if the customer's card is eligible for Dynamic Currency Conversion (DCC). properties: *ref_767 fxRate: required: *ref_768 type: object description: Foreign exchange rate for the transaction. properties: *ref_769 bankTransferPaymentOrderBase: required: *ref_264 type: object allOf: *ref_265 description: Object that contains information about the transaction. bankTransferBreakdownBase: required: *ref_266 type: object description: Object that contains information about the transaction. properties: *ref_267 bankTransferBreakdown: allOf: *ref_770 required: *ref_771 type: object description: Object that contains information about the transaction. properties: *ref_772 bankTransferPaymentOrder: required: *ref_773 type: object allOf: *ref_774 description: Object that contains information about the transaction. bankTransferCustomer: type: object description: Object that contains information about the customer. properties: *ref_268 achBankAccount: required: *ref_276 type: object title: ach description: Object that contains the customer's account details. properties: *ref_277 padBankAccount: required: *ref_278 type: object title: pad description: Object that contains the customer's account details. properties: *ref_279 bankTransferReturnSummary: required: *ref_775 type: object description: Object that contains information about a return. properties: *ref_776 bankTransferResult: type: object description: Object that contains information about the transaction. required: *ref_280 readOnly: true properties: *ref_281 bankTransferPayment: required: *ref_269 type: object description: Object that contains information about the sale and the customer's bank details. properties: *ref_270 bankTransferPaymentPaginatedList: required: *ref_777 type: object allOf: *ref_778 bankTransferRequestBreakdown: allOf: *ref_779 required: *ref_780 type: object description: Object that contains information about the transaction. properties: *ref_781 bankTransferPaymentRequestOrder: required: *ref_782 type: object allOf: *ref_783 description: Object that contains information about the transaction. bankTransferPaymentRequest: required: *ref_784 type: object description: Object that contains information about the sale and the customer's bank details. properties: *ref_785 bankTransferReferencedRefund: required: *ref_786 type: object description: Object that contains information about the payment that you want to refund. properties: *ref_787 representment: type: object description: Object that contains the paymentMethod object. properties: *ref_788 bankTransferRefundOrder: description: Object that contains information about the order. required: *ref_274 type: object allOf: *ref_275 bankTransferRefund: required: *ref_282 type: object properties: *ref_283 bankTransferRefundPaginatedList: required: *ref_789 type: object allOf: *ref_790 bankTransferUnreferencedRefund: required: *ref_791 type: object properties: *ref_792 bankAccountVerificationRequest: required: *ref_793 type: object properties: *ref_794 bankAccountVerificationResult: required: *ref_795 type: object properties: *ref_796 addressType: type: object description: Type of address. required: *ref_797 properties: *ref_798 legalAddress: title: legalAddress required: *ref_799 allOf: *ref_800 business: type: object description: Object that contains information about the business. title: business required: *ref_291 properties: *ref_292 signatureByDirectLink: description: Object that contains signature information if we captured the merchant’s signature by direct link. title: requestedViaDirectLink type: object required: *ref_801 properties: *ref_802 signatureByEmail: description: Object that contains signature information if we captured the merchant’s signature by email. title: requestedViaEmail type: object required: *ref_803 properties: *ref_804 signature: type: object description: "Polymorphic object that contains information about how we captured the owner's signature. \n\nThe value of the type parameter determines which variant you should use:\n-\t`requestedViaDirectLink` - Request signature using a link.\n-\t`requestedViaEmail` - Request signature by email.\n" discriminator: *ref_293 oneOf: *ref_294 merchantPlatform: type: object title: merchant required: *ref_295 properties: *ref_296 paginatedMerchants: type: object title: paginated merchant platforms allOf: *ref_805 timezone: description: Time zone for the processing account. enum: *ref_299 example: America/Chicago maxLength: 28 processing: description: Object that contains information about how we process transactions for the account. type: object title: processing required: *ref_300 properties: *ref_301 commonFunding: type: object properties: *ref_302 createFunding: type: object description: | Object that contains information about the funding schedule of the processing account. allOf: *ref_806 pricingTemplate: type: object title: intent required: *ref_807 properties: *ref_808 pricingAgreement: type: object title: agreement allOf: *ref_809 pricing: type: object description: "Polymorphic object that contains pricing information for the processing account. \n\nThe value of the type parameter determines which variant you should use:\n-\t`intent` - Use a pricing agreement template.\n-\t`agreement` - Create a new pricing agreement.\n" discriminator: *ref_810 oneOf: *ref_811 contact: type: object title: contact required: *ref_313 properties: *ref_314 createProcessingAccount: required: *ref_303 type: object properties: *ref_304 createMerchantAccount: type: object title: create merchant platform required: *ref_812 properties: *ref_813 fundingAccountSummary: type: object title: funding account summary properties: *ref_814 funding: type: object description: Object that contains funding information for the processing account, including funding schedules, funding fees, and details of funding accounts. allOf: *ref_815 processingAccount: required: *ref_305 type: object properties: *ref_306 paginatedProcessingAccounts: type: object title: paginated processing accounts allOf: *ref_816 paginatedContacts: type: object title: paginated Contacts allOf: *ref_817 interchangePlusTiered3AmexOptBlue: type: object title: optBlue required: *ref_818 properties: *ref_819 interchangePlusTiered3AmexDirect: type: object title: direct required: *ref_820 properties: *ref_821 interchangePlusTiered3: type: object title: Interchange Plus with three tiers description: Object that contains information about Interchange Plus with three tiers. properties: *ref_822 required: *ref_823 rewardPay: type: object title: RewardPay Plan description: Object that contains information about RewardPay. properties: *ref_824 required: *ref_825 gatewayUs: type: object description: Object that contains information about the gateway fees. title: gateway fees properties: *ref_826 required: *ref_827 pricingAgreementUs4.0: type: object title: US pricing agreement version 4.0 description: Object that contains information about U.S. pricing intents for Merchant Processing Agreement (MPA) 4.0. required: *ref_828 properties: *ref_829 paginatedOwners: type: object title: paginated Owners allOf: *ref_830 pricingAgreementReminder: description: Object that contains information about the pricing agreement reminder. type: object required: *ref_332 properties: *ref_333 schemas-timezone: type: string description: | Time zone of the terminal. **Note**: If you don't send a value for this parameter, we use the time zone of the processing account. enum: *ref_831 example: America/Chicago maxLength: 28 automaticBatchClose: type: object title: automatic description: Indicates how the merchant batches their transactions. properties: *ref_832 required: *ref_833 manualBatchClose: type: object title: manual description: Indicates how the merchant batches their transactions. properties: *ref_834 required: *ref_835 orderItem: type: object properties: *ref_336 required: *ref_337 processingTerminalSummary: type: object description: Object that contains information about the processing terminal. properties: *ref_836 required: *ref_837 links: type: object description: Array of links related to your order items. properties: *ref_838 terminalOrder: type: object properties: *ref_341 required: *ref_342 trainingProvider: *ref_839 properties-shipping: *ref_840 createTerminalOrder: type: object properties: *ref_841 required: *ref_842 payrocGateway: type: object description: Object that contains the gateway settings for the solution. properties: *ref_843 required: *ref_844 schemas-automaticBatchClose: type: object title: automatic description: Indicates how authorized transactions will be batched for settlement properties: *ref_845 required: *ref_846 schemas-manualBatchClose: type: object title: manual description: Indicates how authorized transactions will be batched for settlement properties: *ref_847 required: *ref_848 tipProcessingEnabled: type: object description: Tip settings properties: *ref_849 required: *ref_850 tipProcessingDisabled: type: object description: Tip settings properties: *ref_851 required: *ref_852 ebtEnabled: type: object description: Object that contains details about EBT transactions. properties: *ref_853 required: *ref_854 ebtDisabled: type: object description: Object that contains details about EBT transactions. properties: *ref_855 required: *ref_856 communicationType: type: string description: Indicates how the device communicates with its host. enum: *ref_857 maxLength: 9 processingTerminal: type: object properties: *ref_344 required: *ref_345 paginatedProcessingTerminals: type: object title: paginated Processing Terminals allOf: *ref_858 uploadAttachment: type: object properties: *ref_859 required: *ref_860 attachment: type: object properties: *ref_351 required: *ref_352 tsys: type: object properties: *ref_861 required: *ref_862 hostConfiguration: type: object description: Object that contains the terminal's host configuration. properties: *ref_863 required: *ref_864 webhook: type: object properties: *ref_865 required: *ref_866 notification: type: object title: Notification method oneOf: *ref_867 discriminator: *ref_868 eventSubscription: type: object title: Event Subscription properties: *ref_348 required: *ref_349 paginatedEventSubscriptions: type: object title: paginated event subscriptions allOf: *ref_869 achDeposit: type: object title: ACH deposit description: Object that contains information about the ACH deposit. properties: *ref_350 achDepositSummary: type: object title: ACH deposit summary description: Object that contains information about the ACH deposit. properties: *ref_870 example: *ref_871 achDepositFee: type: object title: ACH deposit fee description: Object that contains information about the ACH deposit fee. properties: *ref_872 examples: paginatedFundRecipients: summary: Paginated funding recipients. description: Paginated list of funding recipients. value: *ref_873 noActivity: summary: No records found description: Valid request, but no records match the criteria. value: *ref_55 validatorError: summary: Bad Request description: One or more validation errors occurred value: *ref_11 notAuthorized: summary: Not Authorized description: Your identity could not be verified value: *ref_874 forbidden: summary: Forbidden description: You do not have the required permission value: *ref_875 apiError: summary: Api error description: Unable to process your request. value: *ref_876 createFundingRecipient: summary: Create funding recipient description: Create a new funding recipient with owners and funding accounts. value: *ref_877 idempotentKeyMissing: summary: Idempotency key missing description: Idempotency key must be supplied value: *ref_26 kycCheckFailed: summary: KYC check failed description: KYC check failed value: *ref_17 notAcceptable: summary: Not acceptable description: Requested representation not supported value: *ref_878 idempotentKeyInUse: summary: Idempotency key in use description: Idempotency key in use value: *ref_29 fundingRecipient: summary: Funding recipient. description: Funding recipients. value: *ref_879 notFound: summary: Not found description: Resource could not be found value: *ref_340 updateFundingRecipient: summary: Update funding recipient description: Update the details of a funding recipient. value: *ref_880 fundingAccounts: summary: List of funding accounts description: List of funding accounts. value: *ref_881 createFundingAccount: summary: Create funding account description: Create a funding account and add it to a funding recipient. value: *ref_882 fundingAccount: summary: Funding account description: Funding accounts. value: *ref_883 createOwner: summary: Create funding recipient owner description: Add an additional owner to a funding recipient. value: *ref_884 listFundingAccountExample: summary: Paginated funding accounts value: *ref_885 noResults: summary: No results found description: No results found value: *ref_886 fundingAccountExample: summary: Masked funding account example. value: *ref_887 updateFundingAccount: summary: Update funding account description: Update the details of a funding account associated with a funding recipient. value: *ref_888 retrievedOwner: summary: Retrieve owner description: Retrieve a specific owner. value: *ref_889 updateOwner: summary: Update owner description: Update a specific owner. value: *ref_890 paginatedPricingIntent: summary: Paginated pricing intent description: Example of a paginated pricing intent. value: *ref_891 interchangePlus: summary: Interchange Plus description: Create a pricing intent. value: *ref_892 interchangePlusPlus: summary: Interchange Plus Plus description: Create a pricing intent. value: *ref_893 tiered3: summary: Tiered 3 description: Create a pricing intent. value: *ref_894 tiered4: summary: Tiered 4 description: Create a pricing intent. value: *ref_895 tiered6: summary: Tiered 6 description: Create a pricing intent. value: *ref_896 flatRate: summary: Flat Rate description: Create a pricing intent. value: *ref_897 consumerChoice: summary: Consumer Choice description: Create a pricing intent. value: *ref_898 rewardPayChoice: summary: Reward Pay Choice description: Create a pricing intent. value: *ref_899 pricingIntent: summary: Pricing intent description: Pricing intent value: *ref_57 modifyPricingIntent: summary: Create pricing intent description: Create a pricing intent. value: *ref_900 patchPricingIntentRealistic: summary: Partially update pricing intent description: | Partially update an existing pricing intent. Structure your request to follow the RFC 6902 standard. value: *ref_901 patchOperations: summary: Example patch operations that apply the RFC 6902 standard description: | Example patch operations that apply the RFC 6902 standard. value: *ref_103 listInstructionsExample: summary: Paginated instructions list value: *ref_902 parameterError: summary: Bad request description: One or more validation errors occurred. value: *ref_903 paginationError: summary: Bad request description: One or more validation errors occurred value: *ref_904 outsideRecordRange: summary: Bad request description: Requested data outside allowed range. value: *ref_905 createFundingInstruction: summary: Funding instruction description: Create a funding instruction to distribute merchant funds to funding accounts. value: *ref_906 createFundingInstructionMetadata: summary: Funding instruction with metadata description: Create a funding instruction to distribute merchant funds to funding accounts. value: *ref_907 newInstructionAccepted: summary: New instruction accepted. value: *ref_908 newInstructionAcceptedMetadata: summary: Created funding instruction with metadata value: *ref_909 insufficientFunds: summary: Insufficient funds description: You do not have enough funds to complete the request. value: *ref_59 fundingAccountsRestricted: summary: Funding accounts restricted description: Funding accounts restricted. value: *ref_61 recipientAmountValueLimitExceeded: summary: Recipient amount.value limit exceeded description: One or more recipients exceed the 'amount.value' limit for your account value: *ref_62 instructionIdError: summary: Bad request description: One or more validation errors occurred. value: *ref_60 updateFundingInstruction: summary: Update funding instruction description: Update an existing funding instruction to modify merchant funds distribution. value: *ref_910 canNotBeModified: summary: Cannot be modified description: Resource cannot be modified. value: *ref_63 listBalancesExample: summary: Paginated list of merchant balances description: Paginated list of merchant balances. value: *ref_911 paginatedList: summary: Paginated activity records description: Valid payfac account with activity for date range. value: *ref_912 examples-parameterError: summary: Bad request description: One or more validation errors occurred. value: *ref_913 paginatedBatches: summary: Paginated batches value: *ref_914 components-examples-parameterError: summary: Bad Request description: One or more validation errors occurred value: *ref_70 examples-paginationError: summary: Bad Request description: One or more validation errors occurred value: *ref_71 batchIdError: summary: Bad Request description: One or more validation errors occurred value: *ref_67 paginatedTransactions: summary: Paginated transactions value: *ref_915 retrievedTransaction: summary: Retrieve transaction value: *ref_916 transactionIdError: summary: Bad Request description: One or more validation errors occurred value: *ref_917 paginatedAuthorizations: summary: Paginated authorizations value: *ref_918 retrievedAuthorization: summary: Retrieve authorization value: *ref_919 paginatedDisputes: summary: Paginated disputes value: *ref_920 paginatedPaymentLinks: summary: Payment links description: Paginated list of payment links value: *ref_921 multiUsePaymentLinkRequest: summary: Multi-use payment link. description: Create a multi-use payment link. value: *ref_922 singleUsePaymentLinkRequest: summary: Single-use payment link. description: Create a single-use payment link. value: *ref_923 paymentLinkResponse: summary: Payment Link description: Active multi-use payment link. value: *ref_98 resourceExists: summary: Resource already exists description: Resource already exists value: *ref_924 unsupportedMediaType: summary: Unsupported media type description: The payload is in an unsupported format. value: *ref_925 patchPaymentLinkRealistic: summary: Partially update payment link description: | Partially update an existing payment link. Structure your request to follow the RFC 6902 standard. value: *ref_926 deactivatedPaymentLink: summary: Payment link description: Deactivated multi-use payment link. value: *ref_927 paginatedSharingEvents: summary: Sharing events description: Paginated list of payment link sharing events value: *ref_928 sharePaymentLinkRequest: summary: Share a payment link. description: Share a payment link. value: *ref_929 paymentLinkShareEvent: summary: Payment link sharing event. description: Payment link sharing event value: *ref_930 paginatedPaymentPlan: summary: Payment Plan description: Payment Plan value: *ref_931 paymentPlanRequest: summary: Payment Plan description: Payment Plan value: *ref_932 paymentPlanResponse: summary: Payment Plan description: Payment Plan value: *ref_116 patchPaymentPlanRealistic: summary: Update payment plan description: | Make changes to an existing payment plan. Structure your request to follow the [RFC 6902](https://datatracker.ietf.org/doc/html/rfc6902) standard. value: *ref_933 paginatedSubscription: summary: Paginated Subscription description: Example of Paginated Subscription value: *ref_934 subscriptionRequest: summary: Subscription description: Subscription value: *ref_935 subscriptionWithSurchargeResponse: summary: Subscription with surcharge description: Subscription with surcharge value: *ref_133 subscriptionWithConvenienceFeeResponse: summary: Subscription with convenience fee description: Subscription with convenience fee value: *ref_134 patchSubscriptionRealistic: summary: Update subscription description: | Make changes to a subscription. Structure your request to follow the [RFC 6902](https://datatracker.ietf.org/doc/html/rfc6902) standard. value: *ref_936 deactivateSubscription: summary: Deactivate subscription description: Deactivate a subscription value: *ref_937 subscriptionPaymentRequest: summary: Subscription manual payment description: Subscription manual payment value: *ref_938 subscriptionPaymentResponse: summary: Subscription manual payment description: Subscription manual payment value: *ref_939 paginatedSecureToken: summary: Paginated Secure Token description: Paginated Secure Token value: *ref_940 secureTokenRequest: summary: Secure Token description: Secure Token value: *ref_941 secureTokenResponse: summary: Secure Token description: Secure Token value: *ref_160 patchSecureTokenRealistic: summary: Update secure token description: | Update the customer's payment details that are represented by the secure token. Structure your request to follow the [RFC 6902](https://datatracker.ietf.org/doc/html/rfc6902) standard. value: *ref_942 accountUpdateRequest: summary: Update account details description: Account update request by single use token value: *ref_943 payloadTooLarge: summary: Payload too large description: The payload submitted is too large value: *ref_944 singleUseTokenRequest: summary: Create single-use token description: Create a single-use token. The token expires after 30 minutes. value: *ref_945 singleUseTokenResponse: summary: Create single-use token description: Create a single-use token. The token expires after 30 minutes. value: *ref_946 createSessionRequest: summary: Create session request description: Create session request. value: *ref_947 createSessionResponse: summary: Create session response description: Create session response. value: *ref_948 applePaySessions: summary: Apple Pay session description: Start a session with Apple to accept a payment with Apple Pay. value: *ref_949 applePayResponseSession: summary: Apple Pay session response description: Wrapper for the content that Apple returns after starting the Apple Pay session. value: *ref_950 paginatedPayment: summary: Payment description: Payment value: *ref_951 paymentRequest: summary: Card Payment description: Payment value: *ref_952 applePaySaleRequest: summary: Apple Pay Payment value: *ref_953 paymentResponse: summary: Payment description: Payment value: *ref_208 applePaySaleResponse: summary: Apple Pay Payment value: *ref_954 adjustPaymentRequest: summary: Adjust Payment description: Adjust Payment value: *ref_955 adjustPaymentResponse: summary: Adjust Payment description: Adjust Payment value: *ref_956 paymentCaptureRequest: summary: Payment capture description: Capture a payment with itemized breakdown value: *ref_957 reversalPaymentRequest: summary: Reversal Payment description: Reversal Payment value: *ref_958 reversalPaymentResponse: summary: Reversal Payment description: Reversal Payment value: *ref_959 refundPaymentRequest: summary: Refund Payment description: Refund Payment value: *ref_960 refundPaymentResponse: summary: Refund Payment description: Refund Payment value: *ref_961 paymentInstructionRequest: summary: Payment Instruction description: Submit an instruction for initiating a payment on a physical device. value: *ref_962 paymentInstructionInProgress: summary: Payment instruction description: Object that contains information about the progress of the payment instruction. value: *ref_963 paymentInstruction: summary: Payment instruction description: Object that contains information about the progress of the payment instruction. value: *ref_964 paymentInstructionCompleted: summary: Payment instruction already completed description: Payment instruction already completed value: *ref_965 paymentInstructionFailed: summary: Payment instruction failed description: Payment instruction failed value: *ref_966 paginatedRefund: summary: Paginated Refund description: Paginated Refund value: *ref_967 refundRequest: summary: Refund description: Refund value: *ref_968 refundResponse: summary: Refund description: Refund value: *ref_239 adjustRefundRequest: summary: Adjust Refund description: Adjust Refund value: *ref_969 adjustRefundResponse: summary: Adjust Refund description: Adjust Refund value: *ref_970 reverseRefund: summary: Reverse Refund description: Reverse Refund value: *ref_971 refundInstructionRequest: summary: Refund instruction description: Submit an instruction for initiating a refund on a physical device. value: *ref_972 refundInstructionInProgress: summary: Refund instruction description: Object that contains information about the progress of the refund instruction. value: *ref_973 refundInstruction: summary: Refund instruction description: Object that contains information about the progress of the refund instruction. value: *ref_974 refundInstructionCompleted: summary: Refund instruction already completed description: Refund instruction already completed value: *ref_975 refundInstructionFailed: summary: Refund instruction failed description: Refund instruction failed value: *ref_976 signatureInstructionRequest: summary: Signature Instruction description: Submit an instruction for capturing a signature on a physical device. value: *ref_977 signatureInstructionInProgress: summary: Signature instruction description: Object that contains information about the progress of the signature instruction. value: *ref_978 signatureInstruction: summary: Signature instruction description: Object that contains information about the progress of the signature instruction. value: *ref_979 signatureInstructionCompleted: summary: Signature instruction already completed description: Signature instruction already completed value: *ref_980 signatureInstructionFailed: summary: Signature instruction failed description: Signature instruction failed value: *ref_981 signatureResponse: summary: Signature description: A signature response example. value: *ref_982 cardVerificationRequest: summary: Card Verification description: Card Verification value: *ref_983 cardVerificationResponse: summary: Card Verification description: Card Verification value: *ref_984 cardBalanceRequest: summary: Card Balance description: Card Balance value: *ref_985 cardBalanceResponse: summary: Card Balance description: Card Balance value: *ref_986 binLookupRequest: summary: BIN lookup description: BIN lookup value: *ref_987 binLookupResponse: summary: BIN lookup description: BIN lookup value: *ref_988 fxRateRequest: summary: Fx-Rate description: Fx-Rate value: *ref_989 fxRateResponse: summary: Fx-Rate description: Fx-Rate value: *ref_990 paginatedBankTransferPayment: summary: Bank Transfer Payment description: Bank Transfer Payment value: *ref_991 bankTransferPaymentRequestStoreTokenRequest: summary: Store Token Bank Transfer Payment description: Bank Transfer Payment with ACH payload and token storage value: *ref_992 bankTransferPaymentResponseStoreToken: summary: Store Token Bank Transfer Payment description: Bank Transfer Payment with ACH payload and token storage value: *ref_271 bankTransferPaymentDeclined: summary: Declined Payment description: Bank Transfer Payment that was declined with return information value: *ref_993 reverseBankTransferPayment: summary: Reverse Bank Transfer Payment description: Reverse Bank Transfer Payment value: *ref_994 refundBankTransferPaymentRequest: summary: Refund Bank Transfer Payment description: Refund Bank Transfer Payment value: *ref_995 refundBankTransferPaymentResponse: summary: Reverse Bank Transfer Payment description: Reverse Bank Transfer Payment value: *ref_996 representmentBankTransferPaymentRequest: summary: Representment Bank Transfer Payment description: Representment Bank Transfer Payment value: *ref_997 paginatedBankTransferUnreferencedRefundResponse: summary: Paginated Bank Transfer Unreferenced Refund description: Paginated Bank Transfer Unreferenced Refund value: *ref_998 bankTransferUnreferencedRefundRequest: summary: Bank Transfer Unreferenced Refund description: Bank Transfer Unreferenced Refund value: *ref_999 bankTransferUnreferencedRefundResponse: summary: Bank Transfer Unreferenced Refund description: Bank Transfer Unreferenced Refund value: *ref_284 reverseBankTransferUnreferencedRefundResponse: summary: Bank Transfer Unreferenced Refund description: Bank Transfer Unreferenced Refund value: *ref_1000 bankAccountVerificationRequestPad: summary: PAD Bank Account Verification Request description: Bank Account Verification Request for PAD value: *ref_1001 bankAccountVerificationRequestAch: summary: ACH Bank Account Verification Request description: Bank Account Verification Request for ACH value: *ref_1002 bankAccountVerificationResponse: summary: Bank Account Verification Response description: Bank Account Verification Response value: *ref_1003 listMerchantPlatforms: summary: Paginated list of merchant platforms description: Retrieve a list of merchant platforms associated with your account. value: *ref_1004 createMerchantPlatform: summary: Create merchant platform description: Create a merchant platform. value: *ref_1005 merchantPlatformCreated: summary: Created merchant platform description: New merchant platform created value: *ref_1006 processingAccountFailed: summary: Failed processing account description: We successfully created the merchant platform, but failed to add one or more processing accounts. value: *ref_1007 fundingAccountsLimitReached: summary: Funding accounts limit reached description: Funding accounts restricted. You can not have any more than two funding accounts attached to this entity value: *ref_307 tooManyControlProngs: summary: Too many control prongs description: Your request included more than one owner as the control prong. You can set only one owner as the control prong. value: *ref_308 noControlProng: summary: No control prong or authorized signatory description: Your request didn’t indicate which owner is the control prong or the authorized signatory. Set one owner as the control prong or the authorized signatory. value: *ref_309 dailyDiscountAndRewardPayConflict: summary: Cannot select Daily Discount and RewardPayChoice at the same time. description: You can't select Daily Discount with a RewardPayChoice pricing plan. To select Daily Discount, choose a different pricing plan. value: *ref_310 taxIdInUse: summary: Tax ID in use description: The tax ID supplied is already in use. value: *ref_1008 nationalIdInUse: summary: National ID in use description: One or more supplied national IDs are not unique. All national IDs must be unique. value: *ref_1009 retrievedMerchantPlatforms: summary: Retrieve merchant platform description: Retrieve a merchant platform. value: *ref_1010 listProcessingAccounts: summary: Paginated list of processing account description: Retrieve processing accounts associated with a merchant platform. value: *ref_1011 createProcessingAccount: summary: Create merchant platform description: Create a merchant platform. value: *ref_1012 processingAccountCreated: summary: Retrieve merchant platform description: Retrieve a merchant platform. value: *ref_1013 retrieveProcessingAccount: summary: Retrieve processing account description: Retrieve a specific processing account. value: *ref_1014 listProcessingAccountFundingAccounts: summary: List of funding accounts description: List of funding accounts associated with a processing account. value: *ref_1015 listContactsPaginated: summary: Paginated list of processing account contacts description: List of contacts associated with a processing account. value: *ref_1016 retrieveProcessingAccountPricingAgreement: summary: Get processing account pricing agreement description: Retrieve a pricing agreement for a processing account. value: *ref_1017 listProcessingAccountOwners: summary: Paginated list of processing account owners description: Retrieve owners associated with a processing account. value: *ref_1018 createReminderForProcessingAccount: summary: Create reminder for processing account description: | When you create a processing account, we send a copy of the pricing agreement to the merchant to sign. You can choose to send them a copy of the pricing agreement by email, or you can generate a link to the pricing agreement.
If you requested the merchant's signature by email and they don't respond, use our Reminders endpoint to create a reminder and to send another email.
**Note:** You can use the Reminders endpoint only if you request the merchant's signature by email. If you generate a link to the pricing agreement, you can't use the Reminders endpoint. value: *ref_1019 reminderCreated: summary: Reminder created description: Reminder created. value: *ref_1020 notRequestedByEmail: summary: Not requested by email description: We couldn't resend the email to the merchant because you didn't originally choose to send the information by email. value: *ref_1021 contractAlreadySigned: summary: Contract already signed description: We couldn’t resend the email because the merchant already signed the contract. value: *ref_1022 noPricingAgreementExistsForTheProcessingAccount: summary: No pricing agreement exists for the processing account description: We couldn’t resend the email because there is no pricing agreement for the processing account. value: *ref_1023 listTerminalOrders: summary: Paginated list of Terminal Orders description: Retrieve terminal orders associated with a processing account. value: *ref_1024 createTerminalOrder: summary: Terminal order description: | Use this method to order and configure terminals for a processing account. When you create an order, you specify the gateway settings, device settings, and application settings for the terminals. **Note**: You need the ID of the merchant's processing account before you can create an order. If you don't know the processingAccountId, go to [Retrieve a Merchant Platform.](#getMerchantAccounts) value: *ref_1025 terminalOrderCreated: summary: Terminal order description: Terminal order value: *ref_1026 listProcessingTemrinalsPaginated: summary: Paginated list of processing terminals description: List of processing terminals associated with a processing account. value: *ref_1027 retrieveProcessingTerminal: summary: Retrieve processing terminal description: Retrieve a specific processing terminal. value: *ref_1028 contact: summary: Contact object description: Contact object value: *ref_1029 updateContact: summary: Update contact description: Update a specific contact. value: *ref_1030 paginatedEventSubscriptions: summary: Paginated list of Event subscriptions description: Example of a paginated list of event subscriptions value: *ref_1031 createEventSubscription: summary: Create event subscription description: Create an event subscription value: *ref_1032 createEventSubscriptionMetadata: summary: Create event subscription with metadata description: Create an event subscription value: *ref_1033 eventSubscriptionCreated: summary: Event subscription created description: Example of a created event subscription. value: *ref_1034 eventSubscriptionCreatedMetadata: summary: Event subscription created metadata description: Example of a created event subscription. value: *ref_1035 eventSubscription: summary: Event subscription description: Example of an event subscription. value: *ref_1036 updateEventSubscription: summary: Update event subscription description: Update an event subscription value: *ref_1037 patchEventSubscriptionRealistic: summary: Partially update event subscription description: | Partially update an existing event subscription. Structure your request to follow the RFC 6902 standard. value: *ref_1038 patchEventSubscription: summary: Patched event subscription description: Example of a patched event subscription. value: *ref_1039 terminalOrder: summary: Terminal order description: Terminal order value: *ref_1040 paginatedAchDeposits: summary: Paginated ACH deposits value: *ref_1041 achDepositIdError: summary: Bad Request description: One or more validation errors occurred value: *ref_1042 paginatedAchDepositFees: summary: Paginated ACH deposit fees value: *ref_1043 getAttachment: summary: Upload Attachment description: Upload a file attachment value: *ref_1044 responses: '400': description: Invalid request content: *ref_15 '401': description: Identity could not be verified content: *ref_12 '403': description: Do not have permissions to perform this action content: *ref_13 '404': description: Resource not found content: *ref_18 '406': description: Not acceptable content: *ref_19 '409': description: Conflict content: *ref_104 '413': description: Payload too large content: *ref_343 '415': description: Unsupported media type content: *ref_105 '500': description: An error has occured content: *ref_14 headers: location: description: URI reference to created resource. schema: *ref_24 examples: *ref_25 headers-location: description: URI reference to created resource schema: *ref_1045 x-tagGroups: - name: Attachments tags: - Attachments - name: Boarding tags: - Contacts - Merchant platforms - Owners - Pricing intents - Processing accounts - Processing terminals - Terminal orders - name: Payroc Cloud tags: - Payment instructions - Refund instructions - Signature instructions - name: Payments tags: - Apple Pay session - Bank accounts - Bank transfer payments - Bank transfer refunds - Cards - Currency conversion - Hosted Fields - Payments - Payment links - Payment plans - Refunds - Secure tokens - Signatures - Single use tokens - Subscriptions - name: Funding tags: - Funding accounts - Funding instructions - Funding recipients - Funding activity - name: Reporting tags: - Settlement - name: Notifications tags: - Event Subscriptions