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: 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/integrate/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_552 - address - contactMethods - recipientType - taxId - owners - fundingAccounts - doingBusinessAs type: object title: create funding recipient properties: &ref_553 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: Address of the 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 contactMethod objects that you can use to add contact methods for the funding recipient. You must provide at least an email address. 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_538 - type - value type: object title: Email contact method properties: &ref_539 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_540 - type - value type: object title: Phone number contact method properties: &ref_541 type: type: string description: Type of contact method. enum: - phone value: type: string description: Phone number. maxLength: 15 example: '2025550164' - required: &ref_542 - type - value type: object title: Mobile number contact method properties: &ref_543 type: type: string description: Type of contact method. enum: - mobile value: type: string description: Mobile number. maxLength: 15 example: '8445557624' - required: &ref_544 - type - value type: object title: Fax number contact method properties: &ref_545 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_288 - type - value type: object title: identifier properties: &ref_289 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 contactMethod objects. **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. items: discriminator: *ref_2 oneOf: *ref_3 relationship: description: Object that contains information about the owner's relationship to the business. allOf: - required: &ref_547 - isControlProng type: object title: Owner relationship description: Object that contains information about the owner's relationship to the business. properties: &ref_548 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_550 title: payment method discriminator: propertyName: type mapping: ach: '#/components/schemas/PaymentMethodAch' oneOf: - type: object title: ACH payment method properties: &ref_549 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_551 - 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: 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: Address of the 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 contactMethod objects for the funding recipient. 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_526 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_527 - type - title - status - detail examples: notAuthorized: summary: Not Authorized description: Your identity could not be verified value: &ref_867 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_528 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_529 - type - title - status - detail examples: forbidden: summary: Forbidden description: You do not have the required permission value: &ref_868 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_530 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_531 - type - title - status - detail examples: notAcceptable: summary: Not acceptable description: Requested representation not supported value: &ref_870 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_536 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_537 - type - title - status - detail examples: apiError: summary: Api error description: Unable to process your request. value: &ref_869 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_546 - 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_866 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_871 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_337 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_338 - type - title - status - detail examples: notFound: summary: Not found description: Resource could not be found value: &ref_339 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 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_872 - 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 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_873 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 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_554 - 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_874 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_875 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_876 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 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_877 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_878 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_594 - 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: Object that contains information about a pricing intent. oneOf: &ref_56 - type: object title: pricing intent version 5.0 description: Object that contains information about a pricing intent for Merchant Processing Agreement (MPA) 5.0. allOf: &ref_593 - type: object title: base pricing intent description: Object that contains information about the base fees. properties: &ref_555 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_556 - 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_286 - country - version - base properties: &ref_287 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_314 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: Object that contains information about the Platinum Security fee. type: object discriminator: propertyName: billingFrequency mapping: monthly: '#/components/schemas/baseUsMonthly' annual: '#/components/schemas/baseUsAnnual' oneOf: - type: object title: Monthly platinum security required: &ref_557 - billingFrequency properties: &ref_558 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 platinum security required: &ref_559 - billingFrequency properties: &ref_560 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_315 - 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: Object that contains information about card fees. 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_316 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: Object that contains the fees for American Express transactions. discriminator: propertyName: type mapping: optBlue: '#/components/schemas/interchangePlusAmexOptBlue' direct: '#/components/schemas/interchangePlusAmexDirect' oneOf: - type: object title: American Express OptBlue required: &ref_561 - type - volume - transaction properties: &ref_562 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: American Express Direct required: &ref_563 - type - transaction properties: &ref_564 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_317 - planType - fees - type: object title: Interchange Plus Plus description: Object that contains information about Interchange Plus Plus. properties: &ref_569 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: Object that contains the fees for American Express transactions. discriminator: propertyName: type mapping: optBlue: '#/components/schemas/interchangePlusPlusAmexOptBlue' direct: '#/components/schemas/interchangePlusPlusAmexDirect' oneOf: - type: object title: American Express OptBlue required: &ref_565 - type - qualifiedRate - midQualRate - nonQualRate properties: &ref_566 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: American Express Direct required: &ref_567 - type - transaction properties: &ref_568 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_570 - planType - fees - type: object title: Tiered pricing with three tiers description: Object that contains information about tiered pricing with three tiers. properties: &ref_318 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: Object that contains the fees for American Express transactions. discriminator: propertyName: type mapping: optBlue: '#/components/schemas/tiered3AmexOptBlue' direct: '#/components/schemas/tiered3AmexDirect' oneOf: - type: object title: American Express OptBlue required: &ref_571 - type - qualifiedRate - midQualRate - nonQualRate properties: &ref_572 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: American Express Direct required: &ref_573 - type - transaction properties: &ref_574 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_319 - planType - fees - type: object title: Tiered pricing with four tiers description: Object that contains information about tiered pricing with four tiers. properties: &ref_320 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: Object that contains the fees for American Express transactions. discriminator: propertyName: type mapping: optBlue: '#/components/schemas/tiered4AmexOptBlue' direct: '#/components/schemas/tiered4AmexDirect' oneOf: - type: object title: American Express OptBlue required: &ref_575 - type - qualifiedRate - midQualRate - nonQualRate properties: &ref_576 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: American Express Direct required: &ref_577 - type - transaction properties: &ref_578 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_321 - planType - fees - type: object title: Tiered pricing with six tiers description: Object that contains information about tiered pricing with six tiers. properties: &ref_322 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_579 - 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: Object that contains the fees for American Express transactions. discriminator: propertyName: type mapping: optBlue: '#/components/schemas/tiered6AmexOptBlue' direct: '#/components/schemas/tiered6AmexDirect' oneOf: - type: object title: American Express 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: American Express 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_323 - planType - fees - type: object title: Flat Rate Plan description: Object that contains information about Flat Rate. properties: &ref_324 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: Object that contains the fees for American Express transactions. discriminator: propertyName: type mapping: direct: '#/components/schemas/flatRateAmexDirect' oneOf: - type: object title: American Express Direct required: &ref_584 - type - transaction properties: &ref_585 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_325 - planType - fees - type: object title: Consumer Choice Plan description: Object that contains information about ConsumerChoice. properties: &ref_326 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_327 - planType - fees - type: object title: RewardPayChoice Plan description: Object that contains information about RewardPayChoice. properties: &ref_328 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_329 - planType - fees ach: type: object description: Object that contains the fees for ACH transactions. properties: &ref_330 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_586 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_587 - fees services: title: US version 5.0 services array description: Object that contains information about our additional services that the merchant can sign up for. type: array items: &ref_592 title: US version 5.0 service type: object description: Object that contains information about the Hardware Advantage Plan. discriminator: &ref_590 propertyName: name mapping: hardwareAdvantagePlan: '#/components/schemas/hardwareAdvantagePlan' oneOf: &ref_591 - type: object description: Object that contains information about the Hardware Advantage Plan. properties: &ref_588 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_589 - name - enabled uniqueItems: true examples: paginatedResults: summary: Paginated pricing intent description: Example of a paginated pricing intent. value: &ref_879 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: Object that contains information about a pricing intent. oneOf: *ref_56 examples: interchangePlus: summary: Interchange Plus description: Create a pricing intent. value: &ref_880 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_881 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_882 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_883 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_884 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_885 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_886 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_887 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: Object that contains information about a pricing intent. 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_349 type: string examples: &ref_350 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: Object that contains information about a pricing intent. 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: Object that contains information about a pricing intent. oneOf: *ref_56 examples: pricingIntent: summary: Create pricing intent description: Create a pricing intent. value: &ref_888 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_100 title: Patch Operation description: A JSON Patch operation as defined by RFC 6902. discriminator: &ref_607 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_608 - type: object title: Patch Add Operation description: A Patch Add Operation. required: &ref_595 - op - path - value properties: &ref_596 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_597 - op - path properties: &ref_598 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_599 - op - path - value properties: &ref_600 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_601 - op - from - path properties: &ref_602 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_603 - op - from - path properties: &ref_604 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_605 - op - path - value properties: &ref_606 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_101 - 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_889 - 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_102 - 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: Object that contains information about a pricing intent. 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 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_894 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 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 '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_351 type: string format: date examples: &ref_352 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_353 type: string format: date examples: &ref_354 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_890 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_891 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_355 type: integer examples: &ref_356 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 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_62 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 '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_62 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_63 type: string examples: &ref_64 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_609 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_895 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_357 type: string format: date examples: &ref_358 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_359 type: string format: date examples: &ref_360 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_63 examples: *ref_64 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_610 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_611 - 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_896 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_897 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_892 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_893 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_361 type: string format: date examples: &ref_362 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_63 examples: *ref_64 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_65 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_67 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_68 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_898 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_69 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_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: before detail: invalid value message: Expected integer, got abc idError: summary: Bad Request description: One or more validation errors occurred value: &ref_66 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_363 type: integer examples: &ref_364 example: value: 12345 responses: '200': description: Successful request. Returns the requested batch. content: application/json: schema: type: object title: batch properties: *ref_65 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_66 '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_72 type: string format: date examples: &ref_73 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_74 type: integer examples: &ref_75 example: value: 12345 - name: merchantId in: query description: Filter results by the unique identifier that the processor assigned to the merchant. schema: *ref_63 examples: *ref_64 - name: transactionType in: query description: Filter transactions by transaction type. schema: &ref_365 type: string enum: - Capture - Return examples: &ref_366 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_71 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_67 example: *ref_68 settled: type: object title: settlement summary description: Object that contains information about the settlement. properties: &ref_612 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_613 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_76 - 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_77 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_78 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_614 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_899 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_69 paginationError: 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 '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_367 type: integer examples: &ref_368 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_71 example: summary: Retrieve transaction value: 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_900 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_72 examples: *ref_73 - 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_74 examples: *ref_75 - name: merchantId in: query description: Filter results by the unique identifier that the processor assigned to the merchant. schema: *ref_63 examples: *ref_64 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_79 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_76 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_77 card: type: object title: card summary description: Object that contains information about the card. properties: *ref_78 merchant: type: object title: merchant summary description: Object that contains information about the merchant. properties: *ref_67 example: *ref_68 transaction: type: object title: transaction summary description: Object that contains summary information about the transaction that the dispute is linked to. properties: &ref_80 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_901 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_69 paginationError: 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 '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_369 type: integer examples: &ref_370 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_79 example: summary: Retrieve authorization value: 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_371 type: string format: date examples: &ref_372 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_63 examples: *ref_64 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_615 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_81 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_78 merchant: type: object title: merchant summary description: Object that contains information about the merchant. properties: *ref_67 example: *ref_68 transaction: type: object title: transaction summary description: Object that contains summary information about the transaction that the dispute is linked to. properties: *ref_80 required: - data examples: paginatedList: summary: Paginated disputes value: &ref_902 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_69 paginationError: 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 '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_373 type: integer examples: &ref_374 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_81 '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_69 '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_95 maxLength: 50 minLength: 4 type: string examples: &ref_96 example: value: '1234001' requestBody: content: application/json: schema: type: object oneOf: - required: &ref_91 - type - order - authType - paymentMethods - merchantReference type: object title: Multi-use link description: Object that contains information about a multi-use payment link. properties: &ref_92 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_616 - charge type: object description: Object that contains information about the order. properties: &ref_617 description: type: string maxLength: 1024 description: A brief description of the transaction. example: Pie It Forward charitable trust donation charge: type: object description: Indicates whether the merchant or the customer enters the amount for the transaction. oneOf: - required: &ref_83 - type - currency type: object title: Prompt amount description: Object that contains information about the charge when the customer enters the amount of the transaction. properties: &ref_84 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_82 - 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_85 - type - amount - currency type: object title: Preset amount description: Object that contains information about the charge when the merchant enters the amount of the transaction. properties: &ref_86 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_82 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_87 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_88 - paymentUrl - paymentButton type: object readOnly: true description: Object that contains shareable assets for the payment link. properties: &ref_89 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_90 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_93 - type - order - authType - expiresOn - paymentMethods - merchantReference type: object title: Single-use link description: Object that contains information about a single-use payment link. properties: &ref_94 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_618 - orderId - charge type: object description: Object that contains information about the order. properties: &ref_619 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: Indicates whether the merchant or the customer enters the amount for the transaction. oneOf: - required: *ref_83 type: object title: Prompt amount description: Object that contains information about the charge when the customer enters the amount of the transaction. properties: *ref_84 - required: *ref_85 type: object title: Preset amount description: Object that contains information about the charge when the merchant enters the amount of the transaction. properties: *ref_86 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_87 assets: required: *ref_88 type: object readOnly: true description: Object that contains shareable assets for the payment link. properties: *ref_89 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_90 examples: multiUsePaymentLinkRequest: summary: Multi-use payment link. description: Create a multi-use payment link. value: &ref_904 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_905 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 created the payment link. content: application/json: schema: type: object oneOf: - required: *ref_91 type: object title: Multi-use link description: Object that contains information about a multi-use payment link. properties: *ref_92 - required: *ref_93 type: object title: Single-use link description: Object that contains information about a single-use payment link. properties: *ref_94 examples: createdPaymentLink: summary: Payment Link description: Active multi-use payment link. value: &ref_97 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_103 application/problem+json: schema: type: object properties: *ref_27 required: *ref_28 examples: resourceExists: summary: Resource already exists description: Resource already exists value: &ref_906 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_104 application/problem+json: schema: type: object properties: &ref_534 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_535 - type - title - status - detail examples: unsupportedMediaType: summary: Unsupported media type description: The payload is in an unsupported format. value: &ref_907 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_95 examples: *ref_96 - name: merchantReference in: query description: Filter results by the unique identifier that the merchant assigned to the payment link. schema: &ref_375 type: string minLength: 1 maxLength: 48 examples: &ref_376 example: value: LinkRef6543 - name: linkType in: query description: Filter results by the type of link. Send a value of singleUse or multiUse. schema: &ref_377 type: string enum: - multiUse - singleUse examples: &ref_378 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_379 type: string enum: - preset - prompt examples: &ref_380 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_381 type: string enum: - active - completed - deactivated - expired examples: &ref_382 example: value: active - name: recipientName in: query description: Filter results by the customer's name. schema: &ref_107 type: string minLength: 1 maxLength: 48 examples: &ref_108 example: value: Sarah Hazel Hopper - name: recipientEmail in: query description: Filter results by the customer's email address. schema: &ref_109 type: string minLength: 6 maxLength: 128 examples: &ref_110 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_383 type: string format: date examples: &ref_384 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_385 type: string format: date examples: &ref_386 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_620 - count - data - hasMore - limit type: object allOf: &ref_621 - 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 payment links. items: type: object oneOf: - required: *ref_91 type: object title: Multi-use link description: Object that contains information about a multi-use payment link. properties: *ref_92 - required: *ref_93 type: object title: Single-use link description: Object that contains information about a single-use payment link. properties: *ref_94 examples: paginatedResults: summary: Payment links description: Paginated list of payment links value: &ref_903 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_98 type: string minLength: 10 maxLength: 10 examples: &ref_99 example: value: JZURRJBUPS responses: '200': description: Successful request. Returns the payment link. content: application/json: schema: type: object oneOf: - required: *ref_91 type: object title: Multi-use link description: Object that contains information about a multi-use payment link. properties: *ref_92 - required: *ref_93 type: object title: Single-use link description: Object that contains information about a single-use payment link. properties: *ref_94 examples: paymentLink: summary: Payment Link description: Active multi-use payment link. value: *ref_97 '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_98 examples: *ref_99 requestBody: content: application/json: schema: type: array description: A JSON Patch document as defined by RFC 6902. items: *ref_100 example: *ref_101 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_908 - 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_102 required: true responses: '200': description: Successful request. We updated the payment link. content: application/json: schema: type: object oneOf: - required: *ref_91 type: object title: Multi-use link description: Object that contains information about a multi-use payment link. properties: *ref_92 - required: *ref_93 type: object title: Single-use link description: Object that contains information about a single-use payment link. properties: *ref_94 examples: paymentLink: summary: Payment Link description: Active multi-use payment link. value: *ref_97 '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_103 '415': description: Unsupported media type content: *ref_104 '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_98 examples: *ref_99 responses: '200': description: Successful request. We deactivated the payment link. content: application/json: schema: type: object oneOf: - required: *ref_91 type: object title: Multi-use link description: Object that contains information about a multi-use payment link. properties: *ref_92 - required: *ref_93 type: object title: Single-use link description: Object that contains information about a single-use payment link. properties: *ref_94 examples: deactivatedPaymentLink: summary: Payment link description: Deactivated multi-use payment link. value: &ref_909 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_103 '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_98 examples: *ref_99 requestBody: content: application/json: schema: type: object oneOf: - required: &ref_105 - sharingMethod - recipients type: object title: Share via email description: Object that contains the information about a sharing event that the merchant sent by email. properties: &ref_106 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_622 - name - email type: object description: Object that contains the contact details of the recipient. properties: &ref_623 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_911 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 shared the payment link. content: application/json: schema: type: object oneOf: - required: *ref_105 type: object title: Share via email description: Object that contains the information about a sharing event that the merchant sent by email. properties: *ref_106 examples: paymentLinkShareEvent: summary: Payment link sharing event. description: Payment link sharing event value: &ref_912 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_103 '415': description: Unsupported media type content: *ref_104 '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_98 examples: *ref_99 - name: recipientName in: query description: Filter results by the customer's name. schema: *ref_107 examples: *ref_108 - name: recipientEmail in: query description: Filter results by the customer's email address. schema: *ref_109 examples: *ref_110 - 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_624 - count - data - hasMore - limit type: object allOf: &ref_625 - 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 sharing events for the payment link. items: type: object oneOf: - required: *ref_105 type: object title: Share via email description: Object that contains the information about a sharing event that the merchant sent by email. properties: *ref_106 examples: paginatedResults: summary: Sharing events description: Paginated list of payment link sharing events value: &ref_910 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/integrate/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_95 examples: *ref_96 requestBody: content: application/json: schema: required: &ref_113 - paymentPlanId - name - currency - frequency - onDelete - onUpdate - type type: object allOf: &ref_114 - required: &ref_626 - paymentPlanId - name - currency - frequency - onDelete - onUpdate - type type: object properties: &ref_627 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_82 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_631 - type: object description: Object that contains information about the initial cost that a customer pays to set up the subscription. properties: &ref_628 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_111 - subtotal type: object allOf: &ref_112 - required: &ref_629 - subtotal type: object description: | Object that contains information about the taxes that apply to the transaction. properties: &ref_630 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_123 - name - rate type: object properties: &ref_124 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_633 - 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_632 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_111 type: object allOf: *ref_112 examples: paymentPlanRequest: summary: Payment Plan description: Payment Plan value: &ref_914 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_113 type: object allOf: *ref_114 examples: createdPaymentPlan: summary: Payment Plan description: Payment Plan value: &ref_115 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_103 '415': description: Unsupported media type content: *ref_104 '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_95 examples: *ref_96 - 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_634 - count - data - hasMore - limit type: object allOf: &ref_635 - 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_113 type: object allOf: *ref_114 examples: paginatedResults: summary: Payment Plan description: Payment Plan value: &ref_913 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_95 examples: *ref_96 - name: paymentPlanId in: path description: Unique identifier that the merchant assigned to the payment plan. required: true schema: &ref_116 maxLength: 48 minLength: 1 type: string examples: &ref_117 example: value: PlanRef8765 responses: '200': description: Successful request. Returns the requested payment plan. content: application/json: schema: required: *ref_113 type: object allOf: *ref_114 examples: paymentPlan: summary: Payment Plan description: Payment Plan value: *ref_115 '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_95 examples: *ref_96 - name: paymentPlanId in: path description: Unique identifier that the merchant assigned to the payment plan. required: true schema: *ref_116 examples: *ref_117 requestBody: content: application/json: schema: type: array description: A JSON Patch document as defined by RFC 6902. items: *ref_100 example: *ref_101 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_915 - 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_102 required: true responses: '200': description: Successful request. We updated the payment plan. content: application/json: schema: required: *ref_113 type: object allOf: *ref_114 examples: paymentPlan: summary: Payment Plan description: Payment Plan value: *ref_115 '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_103 '415': description: Unsupported media type content: *ref_104 '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_95 examples: *ref_96 - name: paymentPlanId in: path description: Unique identifier that the merchant assigned to the payment plan. required: true schema: *ref_116 examples: *ref_117 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/integrate/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_95 examples: *ref_96 requestBody: content: application/json: schema: required: &ref_643 - paymentMethod - paymentPlanId - startDate - subscriptionId type: object properties: &ref_644 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: Object that contains information about the customer's payment details. discriminator: propertyName: type mapping: secureToken: '#/components/schemas/secureTokenPayload' oneOf: - required: &ref_178 - type - token type: object writeOnly: true title: Secure token description: Object that contains information about the secure token that represents the customer’s payment details. properties: &ref_179 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_641 - description: Object that contains information about the initial cost that a customer pays to set up the subscription. type: object properties: &ref_120 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_118 - subtotal type: object description: | Object that contains information about the taxes to apply to the transaction. allOf: &ref_119 - required: &ref_121 - subtotal type: object properties: &ref_122 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_171 - amount type: object readOnly: true description: Object that contains information about the convenience fee for the transaction. properties: &ref_172 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_169 - name - rate - type properties: &ref_170 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_642 - type: object properties: &ref_125 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_118 type: object description: | Object that contains information about the taxes to apply to the transaction. allOf: *ref_119 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_128 - name - value type: object properties: &ref_129 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_917 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_130 - subscriptionId - processingTerminalId - paymentPlan - secureToken - name - currency - currentState - startDate - type - frequency type: object properties: &ref_131 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_636 - name - paymentPlanId type: object properties: &ref_637 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_137 - customerName - secureTokenId - status - token type: object description: Object that contains information about the secure token. properties: &ref_138 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_82 setupOrder: type: object allOf: &ref_136 - description: Object that contains information about the initial cost that a customer pays to set up the subscription. type: object properties: *ref_120 - type: object properties: breakdown: required: &ref_126 - subtotal type: object description: | Object that contains information about the surcharge and taxes that apply to the transaction. allOf: &ref_127 - required: *ref_121 type: object properties: *ref_122 - 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_168 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_123 type: object properties: *ref_124 recurringOrder: type: object description: | Object that contains information about the cost of each payment. allOf: &ref_638 - type: object properties: *ref_125 - type: object properties: breakdown: required: *ref_126 type: object description: | Object that contains information about the surcharge and taxes that apply to the transaction. allOf: *ref_127 currentState: required: &ref_139 - paidInvoices - status type: object description: A snapshot of the subscription's current state. properties: &ref_140 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_128 type: object properties: *ref_129 examples: createdSubscriptionWithSurcharge: summary: Subscription with surcharge description: Subscription with surcharge value: &ref_132 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_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 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_103 '415': description: Unsupported media type content: *ref_104 '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_95 examples: *ref_96 - 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_391 maxLength: 128 minLength: 1 type: string examples: &ref_392 example: value: Premium%20Club - name: frequency in: query description: Filter by the frequency of subscription payments. schema: &ref_393 type: string enum: - weekly - fortnightly - monthly - quarterly - yearly examples: &ref_394 example: value: monthly - name: status in: query description: Filter by the current status of the subscription. schema: &ref_395 type: string enum: - active - completed - suspended - cancelled examples: &ref_396 example: value: active - name: endDate in: query description: | Format: `YYYY-MM-DD` Filter subscriptions that end on a specific date. schema: &ref_397 type: string format: date examples: &ref_398 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_399 type: string format: date examples: &ref_400 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_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 subscriptions. items: required: *ref_130 type: object properties: *ref_131 examples: paginatedResults: summary: Paginated Subscription description: Example of Paginated Subscription value: &ref_916 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_95 examples: *ref_96 - name: subscriptionId in: path description: Unique identifier that the merchant assigned to the subscription. required: true schema: &ref_134 maxLength: 48 minLength: 1 type: string examples: &ref_135 example: value: SubRef7654 responses: '200': description: Successful request. Returns the requested subscription. content: application/json: schema: required: *ref_130 type: object properties: *ref_131 examples: subscriptionWithSurcharge: summary: Subscription with surcharge description: Subscription with surcharge value: *ref_132 subscriptionWithConvenienceFee: summary: Subscription with convenience fee description: Subscription with convenience fee value: *ref_133 '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_95 examples: *ref_96 - name: subscriptionId in: path description: Unique identifier that the merchant assigned to the subscription. required: true schema: *ref_134 examples: *ref_135 requestBody: required: true content: application/json: schema: type: array description: A JSON Patch document as defined by RFC 6902. items: *ref_100 example: *ref_101 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_918 - 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_102 responses: '200': description: Successful request. We have updated the subscription. content: application/json: schema: required: *ref_130 type: object properties: *ref_131 examples: subscriptionWithSurcharge: summary: Subscription with surcharge description: Subscription with surcharge value: *ref_132 subscriptionWithConvenienceFee: summary: Subscription with convenience fee description: Subscription with convenience fee value: *ref_133 '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_103 '415': description: Unsupported media type content: *ref_104 '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_95 examples: *ref_96 - name: subscriptionId in: path description: Unique identifier that the merchant assigned to the subscription. required: true schema: *ref_134 examples: *ref_135 responses: '200': description: Successful request. We deactivated the subscription. content: application/problem+json: schema: required: *ref_130 type: object properties: *ref_131 examples: deactivateSubscription: summary: Deactivate subscription description: Deactivate a subscription value: &ref_919 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_103 '415': description: Unsupported media type content: *ref_104 '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_95 examples: *ref_96 - name: subscriptionId in: path description: Unique identifier that the merchant assigned to the subscription. required: true schema: *ref_134 examples: *ref_135 responses: '200': description: Successful request. We re-activated the subscription. content: application/json: schema: required: *ref_130 type: object properties: *ref_131 examples: subscriptionWithSurcharge: summary: Subscription with surcharge description: Subscription with surcharge value: *ref_132 subscriptionWithConvenienceFee: summary: Subscription with convenience fee description: Subscription with convenience fee value: *ref_133 '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_103 '415': description: Unsupported media type content: *ref_104 '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_95 examples: *ref_96 - name: subscriptionId in: path description: Unique identifier that the merchant assigned to the subscription. required: true schema: *ref_134 examples: *ref_135 requestBody: content: application/json: schema: required: &ref_645 - order properties: &ref_646 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_136 customFields: type: array description: | Array of customField objects. items: required: *ref_128 type: object properties: *ref_129 examples: subscriptionPaymentRequest: summary: Subscription manual payment description: Subscription manual payment value: &ref_920 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_647 - subscriptionId - processingTerminalId - payment - secureToken - currentState type: object properties: &ref_648 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_232 - amount - currency - dateTime - paymentId - status - responseCode - responseMessage type: object description: Object that contains information about a payment. properties: &ref_233 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_82 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_137 type: object description: Object that contains information about the secure token. properties: *ref_138 currentState: required: *ref_139 type: object description: A snapshot of the subscription's current state. properties: *ref_140 customFields: type: array description: | Array of customField objects. items: required: *ref_128 type: object properties: *ref_129 examples: subscriptionPaymentResponse: summary: Subscription manual payment description: Subscription manual payment value: &ref_921 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_103 '415': description: Unsupported media type content: *ref_104 '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_95 examples: *ref_96 requestBody: content: application/json: schema: required: &ref_678 - source type: object properties: &ref_679 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_175 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_212 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: Customer's contact information. 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_176 - type - value type: object writeOnly: true description: Object that contains the IP address of the device that sent the request. properties: &ref_177 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: Object that contains information about the payment method to tokenize. 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_162 - 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_163 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_164 - 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_165 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_166 - type - cardDetails type: object writeOnly: true title: Card description: Object that contains information about the customer’s payment card. properties: &ref_167 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: Object that contains the details of the payment card. discriminator: propertyName: entryMethod mapping: raw: '#/components/schemas/rawCardDetails' icc: '#/components/schemas/iccCardDetails' keyed: '#/components/schemas/keyedCardDetails' swiped: '#/components/schemas/swipedCardDetails' oneOf: - required: &ref_656 - entryMethod - device - rawData type: object title: Raw description: Object that contains information about the unencrypted card details. properties: &ref_657 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_141 - 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_142 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_654 - quickChip type: object description: Object that contains information about the configuration of the POS terminal. properties: &ref_655 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_660 - entryMethod - device - iccData type: object title: Chip description: Object that contains information about the Integrated Circuit Card (ICC). properties: &ref_661 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_143 - model - dataKsn - serialNumber type: object description: Object that contains information about the encryption details of the POS terminal. allOf: &ref_144 - required: *ref_141 type: object description: Object that contains information about the physical device the merchant used to capture the customer’s card details. properties: *ref_142 - 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_145 - benefitCategory description: Object that contains information about the Electronic Benefit Transfer (EBT) transaction. allOf: &ref_146 - type: object required: &ref_220 - benefitCategory description: Object that contains information about the Electronic Benefit Transfer (EBT) transaction. properties: &ref_221 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_658 - approvalCode - serialNumber type: object description: | Object that contains information about the EBT voucher. **Note:** Vouchers are available only for EBT SNAP payments. properties: &ref_659 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_668 - entryMethod - keyedData type: object title: Keyed description: Object that contains information about the keyed card details. properties: &ref_669 entryMethod: type: string description: Method that the terminal used to capture the card details. enum: - keyed example: keyed keyedData: type: object discriminator: propertyName: dataFormat mapping: fullyEncrypted: '#/components/schemas/fullyEncryptedKeyedDataFormat' partiallyEncrypted: '#/components/schemas/partiallyEncryptedKeyedDataFormat' plainText: '#/components/schemas/plainTextKeyedDataFormat' oneOf: - required: &ref_662 - dataFormat - device - encryptedData type: object title: Encrypted description: Object that contains information about the encrypted card data for keyed transactions. properties: &ref_663 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_143 type: object description: Object that contains information about the encryption details of the POS terminal. allOf: *ref_144 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_664 - dataFormat - device - encryptedPan - expiryDate - maskedPan type: object title: Partially encrypted description: Object that contains information about the partially-encrypted card data for keyed transactions. properties: &ref_665 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_143 type: object description: Object that contains information about the encryption details of the POS terminal. allOf: *ref_144 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: '1225' 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_666 - dataFormat - cardNumber type: object title: Unencrypted description: Object that contains information about the plain-text card data for keyed transactions. properties: &ref_667 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_141 type: object description: Object that contains information about the physical device the merchant used to capture the customer’s card details. properties: *ref_142 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: '1225' 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 discriminator: propertyName: dataFormat mapping: dukpt: '#/components/schemas/dukptPinDetails' oneOf: - required: &ref_147 - dataFormat - pin - pinKsn type: object title: Encrypted description: Object that contains information about encrypted PIN details. properties: &ref_148 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_145 description: Object that contains information about the Electronic Benefit Transfer (EBT) transaction. allOf: *ref_146 - required: &ref_674 - entryMethod - swipedData type: object title: Swiped description: Object that contains information about the customer’s card details for swiped transactions. properties: &ref_675 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 discriminator: propertyName: dataFormat mapping: encrypted: '#/components/schemas/encryptedSwipedDataFormat' plainText: '#/components/schemas/plainTextSwipedDataFormat' oneOf: - required: &ref_670 - dataFormat - device - encryptedData type: object title: Encrypted description: Object that contains information about the encrypted swiped card data. properties: &ref_671 dataFormat: type: string description: Format of the card data. enum: - encrypted example: encrypted device: required: *ref_143 type: object description: Object that contains information about the encryption details of the POS terminal. allOf: *ref_144 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_672 - dataFormat - device - trackData type: object title: Unencrypted description: Object that contains information about plain-text swiped card data. properties: &ref_673 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_141 type: object description: Object that contains information about the physical device the merchant used to capture the customer’s card details. properties: *ref_142 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 discriminator: propertyName: dataFormat mapping: dukpt: '#/components/schemas/dukptPinDetails' oneOf: - required: *ref_147 type: object title: Encrypted description: Object that contains information about encrypted PIN details. properties: *ref_148 ebtDetails: type: object required: *ref_145 description: Object that contains information about the Electronic Benefit Transfer (EBT) transaction. allOf: *ref_146 - required: &ref_180 - type - token type: object writeOnly: true title: Single-use token description: Object that contains information about the single-use token, which represents the customer’s payment details. properties: &ref_181 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 discriminator: propertyName: dataFormat mapping: dukpt: '#/components/schemas/dukptPinDetails' raw: '#/components/schemas/rawPinDetails' oneOf: - required: *ref_147 type: object title: Encrypted description: Object that contains information about encrypted PIN details. properties: *ref_148 - required: &ref_676 - dataFormat - pin type: object title: Unencrypted description: Object that contains information about the unencrypted PIN details. properties: &ref_677 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_145 description: Object that contains information about the Electronic Benefit Transfer (EBT) transaction. allOf: *ref_146 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: Object that contains information for an authentication check on the customer's payment details using the 3-D Secure protocol. discriminator: propertyName: type mapping: gatewayThreeDSecure: '#/components/schemas/gatewayThreeDSecure' thirdPartyThreeDSecure: '#/components/schemas/thirdPartyThreeDSecure' oneOf: - required: &ref_182 - serviceProvider - mpiReference type: object title: Gateway description: Object that contains the 3-D Secure information from our gateway. properties: &ref_183 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_184 - eci - serviceProvider type: object title: Third party description: Object that contains the 3-D Secure information from a third party. properties: &ref_185 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_128 type: object properties: *ref_129 examples: createSecureToken: summary: Secure Token description: Secure Token value: &ref_923 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: '1225' 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_150 - processingTerminalId - secureTokenId - source - status - token type: object description: Object that contains information about the secure token. properties: &ref_151 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_192 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_149 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_649 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_149 contactMethods: type: array uniqueItems: true description: Customer's contact information. 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: Object that contains information about the payment method that we tokenized. type: object discriminator: propertyName: type mapping: ach: '#/components/schemas/achSource' pad: '#/components/schemas/padSource' card: '#/components/schemas/cardSource' oneOf: - required: &ref_152 - type - nameOnAccount - accountNumber - routingNumber type: object title: ACH account description: Object that contains the customer's account details. properties: &ref_153 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_154 - type - nameOnAccount - accountNumber - transitNumber - institutionNumber type: object title: PAD account description: Object that contains the customer's account details. properties: &ref_155 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_156 - type - cardholderName - cardNumber type: object title: Card description: Object that contains the customer's card details. properties: &ref_157 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: '1225' 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_82 debit: type: boolean description: Indicates if the card is a debit card. surcharging: required: &ref_259 - 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_260 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_128 type: object properties: *ref_129 examples: createdSecureToken: summary: Secure Token description: Secure Token value: &ref_159 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: '1225' 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_103 '415': description: Unsupported media type content: *ref_104 '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_95 examples: *ref_96 - name: secureTokenId in: query description: Unique identifier that the merchant assigned to the secure token. schema: &ref_401 maxLength: 200 minLength: 1 type: string examples: &ref_402 example: value: MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa - name: customerName in: query description: Filter by the customer's name. schema: &ref_387 maxLength: 50 minLength: 1 type: string examples: &ref_388 example: value: Sarah%20Hazel%20Hopper - name: phone in: query description: Filter by the customer's phone number. schema: &ref_403 maxLength: 15 minLength: 1 type: string examples: &ref_404 example: value: '2025550165' - name: email in: query description: Filter by the customer's email address. schema: &ref_405 maxLength: 100 minLength: 1 type: string examples: &ref_406 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_407 maxLength: 19 minLength: 12 type: string examples: &ref_408 example: value: '296753123456' - name: first6 in: query description: Filter by the first six digits of the card number. schema: &ref_409 pattern: '[0-9]{6}' type: string examples: &ref_410 example: value: '453985' - name: last4 in: query description: Filter by the last four digits of the card or account number. schema: &ref_389 pattern: '[0-9]{4}' type: string examples: &ref_390 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_652 - count - data - hasMore - limit type: object allOf: &ref_653 - 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_158 - required: *ref_150 type: object description: Object that contains information about the secure token. properties: *ref_151 - type: object properties: source: description: Object that contains information about the payment method that we tokenized. type: object discriminator: propertyName: type mapping: ach: '#/components/schemas/achSourceWithAccountType' pad: '#/components/schemas/padSourceWithAccountType' card: '#/components/schemas/cardSource' oneOf: - allOf: &ref_650 - required: *ref_152 type: object title: ACH account description: Object that contains the customer's account details. properties: *ref_153 - type: object properties: accountType: type: string description: | Indicates the customer's account type. enum: - checking - savings example: checking - allOf: &ref_651 - required: *ref_154 type: object title: PAD account description: Object that contains the customer's account details. properties: *ref_155 - type: object properties: accountType: type: string description: | Indicates the customer's account type. enum: - checking - savings example: checking - required: *ref_156 type: object title: Card description: Object that contains the customer's card details. properties: *ref_157 examples: paginatedResults: summary: Paginated Secure Token description: Paginated Secure Token value: &ref_922 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: '1225' 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_95 examples: *ref_96 - name: secureTokenId in: path required: true description: Unique identifier that the merchant assigned to the secure token. schema: &ref_160 maxLength: 200 minLength: 1 type: string examples: &ref_161 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_158 examples: secureToken: summary: Secure Token description: Secure Token value: *ref_159 '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_95 examples: *ref_96 - name: secureTokenId in: path required: true description: Unique identifier that the merchant assigned to the secure token. schema: *ref_160 examples: *ref_161 requestBody: required: true content: application/json: schema: type: array description: A JSON Patch document as defined by RFC 6902. items: *ref_100 example: *ref_101 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_924 - 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_102 responses: '200': description: Successful request. We updated the customer's payment details. content: application/json: schema: required: *ref_150 type: object description: Object that contains information about the secure token. properties: *ref_151 examples: secureToken: summary: Secure Token description: Secure Token value: *ref_159 '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_103 '415': description: Unsupported media type content: *ref_104 '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_95 examples: *ref_96 - name: secureTokenId in: path required: true description: Unique identifier that the merchant assigned to the secure token. schema: *ref_160 examples: *ref_161 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/integrate/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_95 examples: *ref_96 - name: secureTokenId in: path required: true description: Unique identifier that the merchant assigned to the secure token. schema: *ref_160 examples: *ref_161 requestBody: content: application/json: schema: description: Object that contains the single-use token. discriminator: &ref_682 propertyName: type mapping: singleUseToken: '#/components/schemas/singleUseTokenAccountUpdate' oneOf: &ref_683 - required: &ref_680 - type - token type: object description: Object that contains the token. properties: &ref_681 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_925 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_150 type: object description: Object that contains information about the secure token. properties: *ref_151 examples: accountUpdateResponse: summary: Secure Token description: Secure Token value: *ref_159 '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_103 '413': description: Payload too large content: &ref_1023 application/problem+json: schema: type: object properties: &ref_532 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_533 - type - title - status - detail examples: payloadTooLarge: summary: Payload too large description: The payload submitted is too large value: &ref_926 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_104 '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_411 maxLength: 50 minLength: 4 type: string examples: &ref_412 example: value: '1234001' requestBody: content: application/json: schema: required: &ref_684 - channel - source type: object properties: &ref_685 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: Object that contains information about the payment method to tokenize. type: object discriminator: propertyName: type mapping: ach: '#/components/schemas/achPayload' pad: '#/components/schemas/padPayload' card: '#/components/schemas/cardPayload' oneOf: - required: *ref_162 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_163 - required: *ref_164 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_165 - required: *ref_166 type: object writeOnly: true title: Card description: Object that contains information about the customer’s payment card. properties: *ref_167 examples: createSingleUseToken: summary: Create single-use token description: Create a single-use token. The token expires after 30 minutes. value: &ref_927 channel: web operator: Jane source: type: card cardDetails: entryMethod: keyed cardholderName: Sarah Hazel Hopper keyedData: dataFormat: plainText cardNumber: '4539858876047062' expiryDate: '1225' cvv: '234' required: true responses: '201': description: Successful request. We created the single-use token. content: application/json: schema: required: &ref_686 - processingTerminalId - token - expiresAt - source type: object properties: &ref_687 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: Object that contains information about the customer's payment details. writeOnly: true discriminator: propertyName: type mapping: card: '#/components/schemas/cardPayload' oneOf: - required: *ref_166 type: object writeOnly: true title: Card description: Object that contains information about the customer’s payment card. properties: *ref_167 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: Object that contains information about the payment method that we tokenized. type: object discriminator: propertyName: type mapping: ach: '#/components/schemas/achSource' pad: '#/components/schemas/padSource' card: '#/components/schemas/cardSource' oneOf: - required: *ref_152 type: object title: ACH account description: Object that contains the customer's account details. properties: *ref_153 - required: *ref_154 type: object title: PAD account description: Object that contains the customer's account details. properties: *ref_155 - required: *ref_156 type: object title: Card description: Object that contains the customer's card details. properties: *ref_157 examples: createSingleUseToken: summary: Create single-use token description: Create a single-use token. The token expires after 30 minutes. value: &ref_928 processingTerminalId: '1234001' token: fa2e9e51bc5265a33a5ca41449524d53d1def596ffd8c0904f222183a71a65cdb58835120a65196a48a6375abc4deafe2b7e948689ab9d6aba919e860f32e247 expiresAt: '2024-08-05T19:50:05.723+02:00' source: type: card cardholderName: Sarah Hazel Hopper cardNumber: 453985******7062 expiryDate: '1225' 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_103 '415': description: Unsupported media type content: *ref_104 '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/integrate/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_95 examples: *ref_96 requestBody: content: application/json: schema: required: &ref_688 - libVersion - scenario type: object title: Hosted Fields Initialization description: Object that contains information about Hosted Fields initialization request. properties: &ref_689 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_929 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_690 - processingTerminalId - token - expiresAt type: object properties: &ref_691 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_930 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_103 '415': description: Unsupported media type content: *ref_104 '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/integrate/apple-pay). operationId: applePaySessions parameters: - name: processingTerminalId in: path required: true description: Unique identifier that we assigned to the terminal. schema: *ref_95 examples: *ref_96 requestBody: content: application/json: schema: required: &ref_692 - appleDomainId - appleValidationUrl type: object properties: &ref_693 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_931 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_694 - startSessionResponse type: object properties: &ref_695 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_932 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/integrate/apple-pay) and [Google Pay®](https://docs.payroc.com/guides/integrate/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/integrate/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/integrate/save-payment-details) - Save card details to use in future transactions. \n- [3-D Secure](https://docs.payroc.com/guides/integrate/3-d-secure) - Verify the identity of the cardholder. \n- [Custom fields](https://docs.payroc.com/guides/integrate/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_717 - channel - order - paymentMethod - processingTerminalId type: object properties: &ref_718 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_714 - required: &ref_186 - amount - currency - orderId type: object description: Object that contains information about the payment. allOf: &ref_187 - required: &ref_217 - amount - currency - orderId type: object description: Object that contains details about the transaction. properties: &ref_218 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_82 - 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_82 dccOffer: required: &ref_226 - 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_227 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_82 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_697 - processingModel - sequence type: object description: If you don't use our Subscriptions mechanism, include this section to configure your standing/recurring orders. properties: &ref_698 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_696 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_215 - subtotal type: object description: Object that contains information about the breakdown of the transaction. allOf: &ref_216 - type: object allOf: &ref_712 - required: &ref_188 - subtotal type: object description: Object that contains information about the breakdown of the transaction. properties: &ref_189 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_210 - type type: object properties: &ref_211 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_168 dualPricing: description: Object that contains dual pricing information for the transaction. required: &ref_701 - offered type: object properties: &ref_702 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_699 - applied - rate - amount type: object readOnly: true properties: &ref_700 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: List of taxes. items: type: object description: Object that contains information about the tax details. discriminator: &ref_173 propertyName: type mapping: amount: '#/components/schemas/taxAmount' rate: '#/components/schemas/taxRate' oneOf: &ref_174 - type: object required: &ref_710 - name - amount - type properties: &ref_711 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_169 properties: *ref_170 - 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_171 type: object readOnly: true description: Object that contains information about the convenience fee for the transaction. properties: *ref_172 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_713 - required: &ref_190 - quantity - unitPrice type: object description: List of line items. properties: &ref_191 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_704 - 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: Object that contains information about the tax details. discriminator: *ref_173 oneOf: *ref_174 customer: type: object description: Object that contains the customer's contact details and address information. properties: *ref_175 ipAddress: required: *ref_176 type: object writeOnly: true description: Object that contains the IP address of the device that sent the request. properties: *ref_177 paymentMethod: type: object description: Object that contains information about the customer's payment details. discriminator: propertyName: type mapping: card: '#/components/schemas/cardPayload' secureToken: '#/components/schemas/secureTokenPayload' digitalWallet: '#/components/schemas/digitalWalletPayload' singleUseToken: '#/components/schemas/singleUseTokenPayload' oneOf: - required: *ref_166 type: object writeOnly: true title: Card description: Object that contains information about the customer’s payment card. properties: *ref_167 - required: *ref_178 type: object writeOnly: true title: Secure token description: Object that contains information about the secure token that represents the customer’s payment details. properties: *ref_179 - required: &ref_257 - type - encryptedData - serviceProvider type: object writeOnly: true title: Digital wallet description: Object that contains information about the payment details in the customer’s digital wallet. properties: &ref_258 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/integrate/apple-pay). - `google` - For more information about how to integrate with google Pay, go to [Google Pay®](https://docs.payroc.com/guides/integrate/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_180 type: object writeOnly: true title: Single-use token description: Object that contains information about the single-use token, which represents the customer’s payment details. properties: *ref_181 threeDSecure: type: object description: Object that contains information for an authentication check on the customer's payment details using the 3-D Secure protocol. discriminator: propertyName: serviceProvider mapping: gateway: '#/components/schemas/gatewayThreeDSecure' thirdParty: '#/components/schemas/thirdPartyThreeDSecure' oneOf: - required: *ref_182 type: object title: Gateway description: Object that contains the 3-D Secure information from our gateway. properties: *ref_183 - required: *ref_184 type: object title: Third party description: Object that contains the 3-D Secure information from a third party. properties: *ref_185 credentialOnFile: type: object description: Object that contains information about saving the customer’s payment details. properties: &ref_219 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_715 - operation type: object description: Object that contains information about the transaction if the merchant ran it when the terminal was offline. properties: &ref_716 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_128 type: object properties: *ref_129 examples: paymentRequest: summary: Card Payment description: Payment value: &ref_934 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: '1225' cardNumber: '4539858876047062' customFields: - name: yourCustomField value: abc123 applePaySaleRequest: summary: Apple Pay Payment value: &ref_935 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_213 - card - order - paymentId - processingTerminalId - transactionResult type: object properties: &ref_214 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_193 - required: *ref_186 type: object description: Object that contains information about the payment. allOf: *ref_187 - type: object properties: breakdown: required: &ref_706 - subtotal type: object description: Object that contains information about the breakdown of the transaction. allOf: &ref_707 - type: object allOf: &ref_703 - required: *ref_188 type: object description: Object that contains information about the breakdown of the transaction. properties: *ref_189 - type: object properties: taxes: type: array description: List of taxes. items: required: *ref_123 type: object properties: *ref_124 - 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_171 type: object readOnly: true description: Object that contains information about the convenience fee for the transaction. properties: *ref_172 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_705 - required: *ref_190 type: object description: List of line items. properties: *ref_191 - type: object properties: taxes: type: array description: Array of objects that contain information about each tax that applies to the item. items: required: *ref_123 type: object properties: *ref_124 customer: type: object description: Object that contains the customer's contact details and address information. properties: *ref_192 card: required: &ref_255 - cardNumber - entryMethod - expiryDate - type type: object description: Object that contains the details of the payment card. properties: &ref_256 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_137 type: object description: Object that contains information about the secure token. properties: *ref_138 securityChecks: type: object description: Object that contains information about card verification and security checks. properties: &ref_194 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_195 - hex - value type: object description: Object that contains information about the EMV tag. properties: &ref_196 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_197 - amount - benefitCategory - currency type: object description: Object that contains information about the total funds available in the card. properties: &ref_198 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_82 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_199 - amount - currency - dateTime - refundId - status - responseCode - responseMessage type: object description: Object that contains information about a refund. properties: &ref_200 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_82 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_201 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_202 - capture - refund - fullyReverse - partiallyReverse - incrementAuthorization - adjustTip - addSignature - setAsReady - setAsPending transactionResult: required: &ref_203 - status - responseCode type: object properties: &ref_204 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_82 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_128 type: object properties: *ref_129 examples: createdPayment: summary: Payment description: Payment value: &ref_207 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: '1225' 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_936 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_103 '415': description: Unsupported media type content: *ref_104 '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_234 maxLength: 50 minLength: 4 type: string examples: &ref_235 example: value: '1234001' - name: orderId in: query description: Filter payments by order ID. schema: &ref_413 maxLength: 24 minLength: 1 type: string examples: &ref_414 example: value: OrderRef6543 - name: operator in: query description: Filter payments by operator. schema: &ref_415 maxLength: 50 minLength: 1 type: string examples: &ref_416 example: value: Jane - name: cardholderName in: query description: Filter payments by the cardholder’s name. schema: &ref_417 maxLength: 50 minLength: 1 type: string examples: &ref_418 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_419 pattern: '[0-9]{6}' type: string examples: &ref_420 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_421 pattern: '[0-9]{4}' type: string examples: &ref_422 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_425 type: array items: type: string enum: - noTip - prompted - adjusted examples: &ref_426 example: value: - noTip - prompted - name: type in: query description: Filter payments by transaction type. schema: &ref_427 type: array items: type: string enum: - sale - preAuthorization - preAuthorizationCompletion examples: &ref_428 example: value: - sale - preAuthorization - name: status in: query description: Filter payments by the status of the transaction. schema: &ref_429 type: array items: type: string enum: - ready - pending - declined - complete - referral - pickup - reversal - admin - expired - accepted examples: &ref_430 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_431 type: string format: date-time examples: &ref_432 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_433 type: string format: date-time examples: &ref_434 example: value: '2024-07-03T15:30:00Z' - name: settlementState in: query description: Filter payments by the settlement status of the transaction. schema: &ref_435 type: string enum: - settled - unsettled examples: &ref_436 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_437 type: string format: date examples: &ref_438 example: value: '2024-07-02' - name: paymentLinkId in: query description: Unique identifier that our gateway assigned to the payment link. schema: &ref_439 maxLength: 10 minLength: 10 type: string examples: &ref_440 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_708 - count - data - hasMore - limit type: object allOf: &ref_709 - 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_205 - card - order - paymentId - processingTerminalId - transactionResult type: object properties: &ref_206 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_193 customer: type: object description: Object that contains the customer's contact details and address information. properties: *ref_192 card: required: &ref_230 - cardNumber - expiryDate - type type: object description: Object that contains the details of the payment card. properties: &ref_231 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_137 type: object description: Object that contains information about the secure token. properties: *ref_138 securityChecks: type: object description: Object that contains information about card verification and security checks. properties: *ref_194 emvTags: type: array uniqueItems: true description: Array of emvTag objects. items: required: *ref_195 type: object description: Object that contains information about the EMV tag. properties: *ref_196 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_197 type: object description: Object that contains information about the total funds available in the card. properties: *ref_198 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_199 type: object description: Object that contains information about a refund. properties: *ref_200 supportedOperations: type: array items: *ref_201 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_202 transactionResult: required: *ref_203 type: object properties: *ref_204 description: Object that contains information about the transaction response details. customFields: type: array description: | Array of customField objects. items: required: *ref_128 type: object properties: *ref_129 examples: paginatedResults: summary: Payment description: Payment value: &ref_933 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: '1225' 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: '1225' 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_208 maxLength: 10 minLength: 10 type: string examples: &ref_209 example: value: M2MJOG6O2Y responses: '200': description: Successful request. Returns the payment. content: application/json: schema: required: *ref_205 type: object properties: *ref_206 examples: createdPayment: summary: Payment description: Payment value: *ref_207 '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_208 examples: *ref_209 requestBody: content: application/json: schema: required: &ref_724 - adjustments type: object description: Object that contains the transaction adjustment object. properties: &ref_725 operator: maxLength: 50 minLength: 0 type: string description: Operator who adjusted the payment. example: Jane adjustments: type: array description: Array of objects that contain information about the adjustments to the payment. 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_720 - 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_721 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_719 tip: required: *ref_210 type: object description: Object that contains information about the tip. properties: *ref_211 - required: &ref_241 - 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_242 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_243 - 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_244 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_212 contactMethods: uniqueItems: true description: Customer's contact information. type: array items: discriminator: *ref_2 oneOf: *ref_3 - required: &ref_722 - 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_723 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_937 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_213 type: object properties: *ref_214 examples: adjustPaymentResponse: summary: Adjust Payment description: Adjust Payment value: &ref_938 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: '1225' 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_103 '415': description: Unsupported media type content: *ref_104 '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_208 examples: *ref_209 requestBody: content: application/json: schema: description: Object that contains the details of the payment that the merchant wants to capture. type: object properties: &ref_726 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_215 type: object description: Object that contains information about the breakdown of the transaction. allOf: *ref_216 examples: paymentCapture: summary: Payment capture description: Capture a payment with itemized breakdown value: &ref_939 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_213 type: object properties: *ref_214 examples: payment: summary: Payment description: Payment value: *ref_207 '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_103 '415': description: Unsupported media type content: *ref_104 '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_208 examples: *ref_209 requestBody: content: application/json: schema: type: object properties: &ref_727 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_940 amount: 4999 responses: '200': description: Successful request. We reversed the payment. content: application/json: schema: required: *ref_213 type: object properties: *ref_214 examples: reversalPayment: summary: Reversal Payment description: Reversal Payment value: &ref_941 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: '1225' 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_103 '415': description: Unsupported media type content: *ref_104 '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_208 examples: *ref_209 requestBody: content: application/json: schema: description: Object that contains the details of the payment that the merchant wants to refund. required: &ref_728 - amount - description type: object properties: &ref_729 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_942 amount: 4999 description: Refund for order OrderRef6543 required: true responses: '200': description: Successful request. We refunded the payment. content: application/json: schema: required: *ref_213 type: object properties: *ref_214 examples: refundPayment: summary: Refund Payment description: Refund Payment value: &ref_943 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: '1225' 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_103 '415': description: Unsupported media type content: *ref_104 '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_441 maxLength: 64 minLength: 1 type: string examples: &ref_442 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_733 - order - processingTerminalId type: object description: Object that contains the instructions for initiating a payment on a physical device. properties: &ref_734 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_731 - amount - currency - orderId type: object description: Object that contains information about the payment. allOf: &ref_732 - required: *ref_217 type: object description: Object that contains details about the transaction. properties: *ref_218 - type: object properties: breakdown: type: object allOf: &ref_730 - required: *ref_188 type: object description: Object that contains information about the breakdown of the transaction. properties: *ref_189 - type: object properties: taxes: type: array description: List of taxes. items: type: object required: *ref_169 properties: *ref_170 customer: type: object description: Object that contains the customer's contact details and address information. properties: *ref_175 ipAddress: required: *ref_176 type: object writeOnly: true description: Object that contains the IP address of the device that sent the request. properties: *ref_177 credentialOnFile: type: object description: Object that contains information about saving the customer’s payment details. properties: *ref_219 customizationOptions: type: object description: Object that contains available options to customize certain aspects of an instruction. properties: &ref_245 ebtDetails: type: object required: *ref_220 description: Object that contains information about the Electronic Benefit Transfer (EBT) transaction. properties: *ref_221 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_944 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_222 - paymentInstructionId - status type: object allOf: &ref_223 - type: object description: Object that contains information about the status of the instruction properties: &ref_246 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_945 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_103 '415': description: Unsupported media type content: *ref_104 '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_224 maxLength: 36 minLength: 1 type: string examples: &ref_225 example: value: e743a9165d134678a9100ebba3b29597 responses: '200': description: Successful request. Returns the current status of the requested payment instruction. content: application/json: schema: required: *ref_222 type: object allOf: *ref_223 examples: paymentInstruction: summary: Payment instruction description: Object that contains information about the progress of the payment instruction. value: &ref_946 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_224 examples: *ref_225 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_947 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_948 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_737 - 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_738 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_228 - amount - currency - description - orderId type: object description: Object that contains information about the refund. allOf: &ref_229 - required: *ref_217 type: object description: Object that contains details about the transaction. properties: *ref_218 - 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_82 dccOffer: required: *ref_226 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_227 customer: type: object description: Object that contains the customer's contact details and address information. properties: *ref_175 ipAddress: required: *ref_176 type: object writeOnly: true description: Object that contains the IP address of the device that sent the request. properties: *ref_177 refundMethod: description: Object that contains information about how the merchant refunds the customer. type: object discriminator: propertyName: type mapping: card: '#/components/schemas/cardPayload' secureToken: '#/components/schemas/secureTokenPayload' oneOf: - required: *ref_166 type: object writeOnly: true title: Card description: Object that contains information about the customer’s payment card. properties: *ref_167 - required: *ref_178 type: object writeOnly: true title: Secure token description: Object that contains information about the secure token that represents the customer’s payment details. properties: *ref_179 customFields: type: array description: | Array of customField objects. items: required: *ref_128 type: object properties: *ref_129 examples: refund: summary: Refund description: Refund value: &ref_950 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: '1225' cardNumber: '4539858876047062' customFields: - name: yourCustomField value: abc123 required: true responses: '201': description: Successful request. We processed the refund. content: application/json: schema: required: &ref_236 - card - order - processingTerminalId - refundId - transactionResult type: object description: Object that contains information about the retrieved refund. properties: &ref_237 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_228 type: object description: Object that contains information about the refund. allOf: *ref_229 customer: type: object description: Object that contains the customer's contact details and address information. properties: *ref_192 card: required: *ref_230 type: object description: Object that contains the details of the payment card. properties: *ref_231 payment: required: *ref_232 type: object description: Object that contains information about a payment. properties: *ref_233 supportedOperations: type: array items: *ref_201 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_202 transactionResult: required: *ref_203 type: object properties: *ref_204 description: Object that contains information about the transaction response details. customFields: type: array description: | Array of customField objects. items: required: *ref_128 type: object properties: *ref_129 examples: refund: summary: Refund description: Refund value: &ref_238 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: '1225' 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_103 '415': description: Unsupported media type content: *ref_104 '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_234 examples: *ref_235 - name: orderId in: query description: Filter refunds by the unique identifier that the merchant assigned to the order. schema: &ref_443 maxLength: 24 minLength: 1 type: string examples: &ref_444 example: value: OrderRef6543 - name: operator in: query description: Filter refunds by the operator who initiated the request. schema: &ref_445 maxLength: 50 minLength: 1 type: string examples: &ref_446 example: value: Jane - name: cardholderName in: query description: Filter refunds by cardholder name. schema: &ref_447 maxLength: 50 minLength: 1 type: string examples: &ref_448 example: value: Sarah%20Hazel%20Hopper - name: first6 in: query description: Filter refunds by the first six digits of the card number. schema: &ref_449 pattern: '[0-9]{6}' type: string examples: &ref_450 example: value: '453985' - name: last4 in: query description: Filter refunds by the last four digits of the card number. schema: &ref_451 pattern: '[0-9]{4}' type: string examples: &ref_452 example: value: '7062' - name: tender in: query description: Filter by tender type. schema: &ref_423 type: string enum: - ebt - creditDebit examples: &ref_424 example: value: ebt - name: status in: query description: Filter refunds by the current status of the refund. schema: &ref_453 type: array items: type: string enum: - ready - pending - declined - complete - referral - pickup - reversal - admin - expired - accepted examples: &ref_454 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_455 type: string format: date-time examples: &ref_456 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_457 type: string format: date-time examples: &ref_458 example: value: '2024-07-03T15:30:00Z' - name: settlementState in: query description: Status of the settlement. schema: &ref_459 type: string enum: - settled - unsettled examples: &ref_460 example: value: settled - name: settlementDate in: query description: Date the transaction was settled. schema: &ref_461 type: string format: date examples: &ref_462 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_735 - count - data - hasMore - limit type: object description: Object that contains information about refund objects. allOf: &ref_736 - 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_236 type: object description: Object that contains information about the retrieved refund. properties: *ref_237 examples: paginatedResults: summary: Paginated Refund description: Paginated Refund value: &ref_949 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: '1225' 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_239 maxLength: 10 minLength: 10 type: string examples: &ref_240 example: value: CD3HN88U9F responses: '200': description: Successful request. Returns the specific refund. content: application/json: schema: required: *ref_236 type: object description: Object that contains information about the retrieved refund. properties: *ref_237 examples: refundResponse: summary: Refund description: Refund value: *ref_238 '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_239 examples: *ref_240 requestBody: content: application/json: schema: required: &ref_739 - adjustments type: object description: Object that contains information about the adjustment to the refund. properties: &ref_740 operator: maxLength: 50 minLength: 0 type: string description: Operator who requested the adjustment to the refund. example: Jane adjustments: type: array description: Array of objects that contain information about the adjustments to the refund. uniqueItems: true items: discriminator: propertyName: type mapping: status: '#/components/schemas/statusAdjustment' customer: '#/components/schemas/customerAdjustment' oneOf: - required: *ref_241 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_242 - required: *ref_243 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_244 examples: refundRequest: summary: Adjust Refund description: Adjust Refund value: &ref_951 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_236 type: object description: Object that contains information about the retrieved refund. properties: *ref_237 examples: refundResponse: summary: Adjust Refund description: Adjust Refund value: &ref_952 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: '1225' 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_103 '415': description: Unsupported media type content: *ref_104 '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_239 examples: *ref_240 responses: '200': description: Successful request. We voided the refund. content: application/json: schema: required: *ref_236 type: object description: Object that contains information about the retrieved refund. properties: *ref_237 examples: refundResponse: summary: Reverse Refund description: Reverse Refund value: &ref_953 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: '1225' 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_103 '415': description: Unsupported media type content: *ref_104 '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_743 - order - processingTerminalId type: object description: Object that contains information about the instruction request to initiate a refund on a payment device. properties: &ref_744 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_741 - amount - currency - description - orderId type: object description: Object that contains information about the refund. allOf: &ref_742 - required: *ref_217 type: object description: Object that contains details about the transaction. properties: *ref_218 - type: object customer: type: object description: Object that contains the customer's contact details and address information. properties: *ref_175 ipAddress: required: *ref_176 type: object writeOnly: true description: Object that contains the IP address of the device that sent the request. properties: *ref_177 customizationOptions: type: object description: Object that contains available options to customize certain aspects of an instruction. properties: *ref_245 examples: refundInstructionRequest: summary: Refund instruction description: Submit an instruction for initiating a refund on a physical device. value: &ref_954 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_247 - refundInstructionId - status type: object allOf: &ref_248 - type: object description: Object that contains information about the status of the instruction properties: *ref_246 - 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_955 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_103 '415': description: Unsupported media type content: *ref_104 '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_249 maxLength: 36 minLength: 1 type: string examples: &ref_250 example: value: a37439165d134678a9100ebba3b29597 responses: '200': description: Successful request. Returns the current status of the requested refund instruction. content: application/json: schema: required: *ref_247 type: object allOf: *ref_248 examples: refundInstruction: summary: Refund instruction description: Object that contains information about the progress of the refund instruction. value: &ref_956 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_249 examples: *ref_250 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_957 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_958 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_463 maxLength: 64 minLength: 1 type: string examples: &ref_464 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_745 - processingTerminalId type: object description: Object that contains the instructions for capturing a signature on a physical device. properties: &ref_746 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_959 processingTerminalId: '1234001' responses: '202': description: Successful request. We accepted the signature instruction. content: application/json: schema: required: &ref_251 - signatureInstructionId - status type: object allOf: &ref_252 - type: object description: Object that contains information about the status of the instruction properties: *ref_246 - 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_960 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_103 '415': description: Unsupported media type content: *ref_104 '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_253 maxLength: 36 minLength: 1 type: string examples: &ref_254 example: value: a37439165d134678a9100ebba3b29597 responses: '200': description: Successful request. Returns the signature instruction. content: application/json: schema: required: *ref_251 type: object allOf: *ref_252 examples: signatureInstruction: summary: Signature instruction description: Object that contains information about the progress of the signature instruction. value: &ref_961 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_253 examples: *ref_254 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_962 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_963 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_465 type: string minLength: 10 maxLength: 10 examples: &ref_466 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_964 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_747 - card - processingTerminalId type: object properties: &ref_748 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_175 card: type: object description: Object that contains information about the card. discriminator: propertyName: type mapping: card: '#/components/schemas/cardPayload' oneOf: - required: *ref_166 type: object writeOnly: true title: Card description: Object that contains information about the customer’s payment card. properties: *ref_167 examples: cardVerificationRequest: summary: Card Verification description: Card Verification value: &ref_965 operator: Jane processingTerminalId: '1234001' card: type: card cardDetails: entryMethod: keyed cardholderName: Sarah Hazel Hopper cardholderSignature: a1b1c012345678a000b000c0012345d0e0f010g10061a031i001j071k0a1b0c1d0e1234567890120f1g0h1i0j1k0a1b0123451c012d0e1f0g1h0i1j123k1a1b1c1d1e1f1g123h1i1j1k1a1b1c1d1e1f1g123h123i1j123k12340a120a12345b012c0123012d0d1e0f1g0h1i123j123k10000 keyedData: dataFormat: plainText cardNumber: '4539858876047062' expiryDate: '1225' required: true responses: '200': description: Successful request. Returns the verification status of the card details. content: application/json: schema: required: &ref_749 - processingTerminalId - verified type: object properties: &ref_750 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_255 type: object description: Object that contains the details of the payment card. properties: *ref_256 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_203 type: object properties: *ref_204 description: Object that contains information about the transaction response details. examples: cardVerificationResponse: summary: Card Verification description: Card Verification value: &ref_966 operator: Jane processingTerminalId: '1234001' card: type: Visa Credit entryMethod: keyed cardholderName: Sarah Hazel Hopper cardholderSignature: a1b1c012345678a000b000c0012345d0e0f010g10061a031i001j071k0a1b0c1d0e1234567890120f1g0h1i0j1k0a1b0123451c012d0e1f0g1h0i1j123k1a1b1c1d1e1f1g123h1i1j1k1a1b1c1d1e1f1g123h123i1j123k12340a120a12345b012c0123012d0d1e0f1g0h1i123j123k10000 cardNumber: 453985******7062 expiryDate: '1225' 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_103 '415': description: Unsupported media type content: *ref_104 '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_751 - card - currency - processingTerminalId type: object properties: &ref_752 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_82 customer: type: object description: Object that contains the customer's contact details and address information. properties: *ref_175 card: type: object description: Object that contains information about the card. discriminator: propertyName: type mapping: card: '#/components/schemas/cardPayload' singleUseToken: '#/components/schemas/singleUseTokenPayload' oneOf: - required: *ref_166 type: object writeOnly: true title: Card description: Object that contains information about the customer’s payment card. properties: *ref_167 - required: *ref_180 type: object writeOnly: true title: Single-use token description: Object that contains information about the single-use token, which represents the customer’s payment details. properties: *ref_181 examples: cardBalanceRequest: summary: Card Balance description: Card Balance value: &ref_967 operator: Jane processingTerminalId: '1234001' currency: USD card: type: card cardDetails: entryMethod: keyed cardholderName: Sarah Hazel Hopper cardholderSignature: a1b1c012345678a000b000c0012345d0e0f010g10061a031i001j071k0a1b0c1d0e1234567890120f1g0h1i0j1k0a1b0123451c012d0e1f0g1h0i1j123k1a1b1c1d1e1f1g123h1i1j1k1a1b1c1d1e1f1g123h123i1j123k12340a120a12345b012c0123012d0d1e0f1g0h1i123j123k10000 keyedData: dataFormat: plainText cardNumber: '4539858876047062' expiryDate: '1225' 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_753 - card - processingTerminalId type: object properties: &ref_754 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_255 type: object description: Object that contains the details of the payment card. properties: *ref_256 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_968 operator: Jane processingTerminalId: '1234001' card: type: Common Benefit Identification Card entryMethod: keyed cardholderName: Sarah Hazel Hopper cardholderSignature: a1b1c012345678a000b000c0012345d0e0f010g10061a031i001j071k0a1b0c1d0e1234567890120f1g0h1i0j1k0a1b0123451c012d0e1f0g1h0i1j123k1a1b1c1d1e1f1g123h1i1j1k1a1b1c1d1e1f1g123h123i1j123k12340a120a12345b012c0123012d0d1e0f1g0h1i123j123k10000 cardNumber: 453985******7062 expiryDate: '1225' 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_103 '415': description: Unsupported media type content: *ref_104 '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_757 - card type: object properties: &ref_758 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_82 card: type: object description: Object that contains information about the card. discriminator: propertyName: type mapping: card: '#/components/schemas/cardPayload' cardBin: '#/components/schemas/cardBinPayload' secureToken: '#/components/schemas/secureTokenPayload' digitalWallet: '#/components/schemas/digitalWalletPayload' oneOf: - required: *ref_166 type: object writeOnly: true title: Card description: Object that contains information about the customer’s payment card. properties: *ref_167 - required: &ref_755 - type - bin type: object writeOnly: true title: Card BIN description: Object that contains information about the card's bank identification number (BIN). properties: &ref_756 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_178 type: object writeOnly: true title: Secure token description: Object that contains information about the secure token that represents the customer’s payment details. properties: *ref_179 - required: *ref_257 type: object writeOnly: true title: Digital wallet description: Object that contains information about the payment details in the customer’s digital wallet. properties: *ref_258 examples: binLookupRequest: summary: BIN lookup description: BIN lookup value: &ref_969 operator: Jane processingTerminalId: '1234001' card: type: card cardDetails: entryMethod: keyed cardholderName: Sarah Hazel Hopper cardholderSignature: a1b1c012345678a000b000c0012345d0e0f010g10061a031i001j071k0a1b0c1d0e1234567890120f1g0h1i0j1k0a1b0123451c012d0e1f0g1h0i1j123k1a1b1c1d1e1f1g123h1i1j1k1a1b1c1d1e1f1g123h123i1j123k12340a120a12345b012c0123012d0d1e0f1g0h1i123j123k10000 keyedData: dataFormat: plainText cardNumber: '4539858876047062' expiryDate: '1225' required: true responses: '200': description: Successful request. Returns the BIN information. content: application/json: schema: required: &ref_261 - type - cardNumber type: object readOnly: true properties: &ref_262 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_82 debit: type: boolean description: Indicates if the card is a debit card. surcharging: required: *ref_259 type: object description: Object that contains surcharge information. Our gateway returns this object only if the merchant adds a surcharge to transactions. properties: *ref_260 description: Object that contains information about the card. examples: binLookupResponse: summary: BIN lookup description: BIN lookup value: &ref_970 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_103 '415': description: Unsupported media type content: *ref_104 '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_759 - baseAmount - baseCurrency - channel - paymentMethod - processingTerminalId type: object properties: &ref_760 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_82 paymentMethod: type: object description: Object that contains information about the customer's payment details. discriminator: propertyName: type mapping: card: '#/components/schemas/cardPayload' secureToken: '#/components/schemas/secureTokenPayload' digitalWallet: '#/components/schemas/digitalWalletPayload' oneOf: - required: *ref_166 type: object writeOnly: true title: Card description: Object that contains information about the customer’s payment card. properties: *ref_167 - required: *ref_178 type: object writeOnly: true title: Secure token description: Object that contains information about the secure token that represents the customer’s payment details. properties: *ref_179 - required: *ref_257 type: object writeOnly: true title: Digital wallet description: Object that contains information about the payment details in the customer’s digital wallet. properties: *ref_258 examples: fxRateRequest: summary: Fx-Rate description: Fx-Rate value: &ref_971 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: '1225' required: true responses: '200': description: Successful request. Returns the currency conversion rate for the transaction. content: application/json: schema: required: &ref_763 - baseAmount - baseCurrency - cardInfo - inquiryResult - processingTerminalId type: object description: Foreign exchange rate for the transaction. properties: &ref_764 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_82 inquiryResult: required: &ref_761 - dccOffered type: object description: Object that indicates if the customer's card is eligible for Dynamic Currency Conversion (DCC). properties: &ref_762 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_226 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_227 cardInfo: required: *ref_261 type: object readOnly: true properties: *ref_262 description: Object that contains information about the card. examples: fxRateResponse: summary: Fx-Rate description: Fx-Rate value: &ref_972 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_103 '415': description: Unsupported media type content: *ref_104 '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_779 - order - paymentMethod - processingTerminalId type: object description: Object that contains information about the sale and the customer's bank details. properties: &ref_780 processingTerminalId: maxLength: 50 minLength: 4 type: string description: Unique identifier that we assigned to the terminal. example: ready order: required: &ref_777 - amount - currency - orderId type: object allOf: &ref_778 - required: &ref_263 - amount - currency - orderId type: object allOf: &ref_264 - required: *ref_217 type: object description: Object that contains details about the transaction. properties: *ref_218 - 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_82 description: Object that contains information about the transaction. - type: object properties: breakdown: allOf: &ref_774 - required: &ref_265 - subtotal type: object description: Object that contains information about the transaction. properties: &ref_266 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_210 type: object properties: *ref_211 required: &ref_775 - subtotal type: object description: Object that contains information about the transaction. properties: &ref_776 taxes: type: array description: Array of tax objects. items: type: object required: *ref_169 properties: *ref_170 description: Object that contains information about the transaction. customer: type: object description: Object that contains information about the customer. properties: &ref_267 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: Customer's contact information. 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_219 paymentMethod: type: object description: Object that contains information about the customer's payment details. discriminator: propertyName: type mapping: ach: '#/components/schemas/achPayload' pad: '#/components/schemas/padPayload' secureToken: '#/components/schemas/secureTokenPayload' singleUseToken: '#/components/schemas/singleUseTokenPayload' oneOf: - required: *ref_162 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_163 - required: *ref_164 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_165 - required: *ref_178 type: object writeOnly: true title: Secure token description: Object that contains information about the secure token that represents the customer’s payment details. properties: *ref_179 - required: *ref_180 type: object writeOnly: true title: Single-use token description: Object that contains information about the single-use token, which represents the customer’s payment details. properties: *ref_181 customFields: type: array description: | Array of customField objects. items: required: *ref_128 type: object properties: *ref_129 examples: createdBankTransferPaymentStoreToken: summary: Store Token Bank Transfer Payment description: Bank Transfer Payment with ACH payload and token storage value: &ref_974 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_268 - bankAccount - order - paymentId - processingTerminalId - transactionResult type: object description: Object that contains information about the sale and the customer's bank details. properties: &ref_269 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_768 - amount - currency - orderId type: object allOf: &ref_769 - required: *ref_263 type: object allOf: *ref_264 description: Object that contains information about the transaction. - type: object properties: breakdown: allOf: &ref_765 - required: *ref_265 type: object description: Object that contains information about the transaction. properties: *ref_266 required: &ref_766 - subtotal type: object description: Object that contains information about the transaction. properties: &ref_767 taxes: type: array description: Array of tax objects. items: required: *ref_123 type: object properties: *ref_124 description: Object that contains information about the transaction. customer: type: object description: Object that contains information about the customer. properties: *ref_267 bankAccount: description: Object that contains information about the bank account. type: object discriminator: propertyName: type mapping: ach: '#/components/schemas/achBankAccount' pad: '#/components/schemas/padBankAccount' oneOf: - required: &ref_275 - accountNumber - nameOnAccount - routingNumber - type type: object title: ACH account description: Object that contains the customer's account details. properties: &ref_276 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_137 type: object description: Object that contains information about the secure token. properties: *ref_138 - required: &ref_277 - accountNumber - institutionNumber - nameOnAccount - transitNumber - type type: object title: PAD account description: Object that contains the customer's account details. properties: &ref_278 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_137 type: object description: Object that contains information about the secure token. properties: *ref_138 refunds: type: array uniqueItems: true description: List of refunds issued against the payment. items: required: *ref_199 type: object description: Object that contains information about a refund. properties: *ref_200 returns: type: array uniqueItems: true description: List of returns issued against the payment. items: required: &ref_770 - date - paymentId - represented - returnCode - returnReason type: object description: Object that contains information about a return. properties: &ref_771 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_232 type: object properties: *ref_233 transactionResult: type: object description: Object that contains information about the transaction. required: &ref_279 - responseMessage - status - type readOnly: true properties: &ref_280 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_82 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_128 type: object properties: *ref_129 examples: createdBankTransferPaymentStoreToken: summary: Store Token Bank Transfer Payment description: Bank Transfer Payment with ACH payload and token storage value: &ref_270 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_103 '415': description: Unsupported media type content: *ref_104 '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_467 maxLength: 50 minLength: 4 type: string examples: &ref_468 example: value: '1234001' - name: orderId in: query description: Filter results by the order ID of the payment. schema: &ref_469 maxLength: 24 minLength: 1 type: string examples: &ref_470 example: value: OrderRef6543 - name: nameOnAccount in: query description: Filter results by the account holder's name. schema: &ref_471 maxLength: 50 minLength: 1 type: string examples: &ref_472 example: value: Sarah%20Hazel%20Hopper - name: last4 in: query description: Filter results by the last four digits of the account number. schema: &ref_473 pattern: '[0-9]{4}' type: string examples: &ref_474 example: value: '7890' - name: type in: query description: Filter results by transaction type. schema: &ref_475 type: array items: type: string enum: - payment - accountVerification examples: &ref_476 example: value: - payment - name: status in: query description: Filter results by the status of the payment. schema: &ref_477 type: array items: type: string enum: - ready - pending - declined - complete - admin - reversal - returned examples: &ref_478 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_479 type: string format: date-time examples: &ref_480 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_481 type: string format: date-time examples: &ref_482 example: value: '2024-07-31T23:59:59Z' - name: settlementState in: query description: Filter results by the settlement status. schema: &ref_483 type: string enum: - settled - unsettled examples: &ref_484 example: value: settled - name: settlementDate in: query description: Filter results by the settlement date. Send a value in **YYYY-MM-DD** format. schema: &ref_485 type: string format: date examples: &ref_486 example: value: '2024-07-15' - name: paymentLinkId in: query description: Filter results by the paymentLinkId. schema: &ref_487 maxLength: 10 minLength: 10 type: string examples: &ref_488 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_772 - count - data - hasMore - limit type: object allOf: &ref_773 - 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_268 type: object description: Object that contains information about the sale and the customer's bank details. properties: *ref_269 examples: paginatedResults: summary: Bank Transfer Payment description: Bank Transfer Payment value: &ref_973 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_271 maxLength: 10 minLength: 10 type: string examples: &ref_272 example: value: M2MJOG6O2Y responses: '200': description: Successful request. Returns the specific payment. content: application/json: schema: required: *ref_268 type: object description: Object that contains information about the sale and the customer's bank details. properties: *ref_269 examples: bankTransferPayment: summary: Store Token Bank Transfer Payment description: Bank Transfer Payment with ACH payload and token storage value: *ref_270 '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_271 examples: *ref_272 responses: '200': description: Successful request. We voided the payment. content: application/json: schema: required: *ref_268 type: object description: Object that contains information about the sale and the customer's bank details. properties: *ref_269 examples: reverseBankTransferPayment: summary: Reverse Bank Transfer Payment description: Reverse Bank Transfer Payment value: &ref_975 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_103 '415': description: Unsupported media type content: *ref_104 '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_271 examples: *ref_272 requestBody: content: application/json: schema: required: &ref_781 - amount - description type: object description: Object that contains information about the payment that you want to refund. properties: &ref_782 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_976 amount: 4999 description: amount to refund required: true responses: '200': description: Successful request. We refunded the payment. content: application/json: schema: required: *ref_268 type: object description: Object that contains information about the sale and the customer's bank details. properties: *ref_269 examples: bankTransferPayment: summary: Reverse Bank Transfer Payment description: Reverse Bank Transfer Payment value: &ref_977 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_103 '415': description: Unsupported media type content: *ref_104 '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_271 examples: *ref_272 requestBody: content: application/json: schema: type: object description: Object that contains the paymentMethod object. properties: &ref_783 paymentMethod: type: object description: Object that contains information about the customer's payment details. discriminator: propertyName: type mapping: ach: '#/components/schemas/achPayload' secureToken: '#/components/schemas/secureTokenPayload' oneOf: - required: *ref_162 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_163 - required: *ref_178 type: object writeOnly: true title: Secure token description: Object that contains information about the secure token that represents the customer’s payment details. properties: *ref_179 examples: representBankTransferPayment: summary: Representment Bank Transfer Payment description: Representment Bank Transfer Payment value: &ref_978 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_268 type: object description: Object that contains information about the sale and the customer's bank details. properties: *ref_269 examples: bankTransferPayment: summary: Store Token Bank Transfer Payment description: Bank Transfer Payment with ACH payload and token storage value: *ref_270 '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_103 '415': description: Unsupported media type content: *ref_104 '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_786 - order - processingTerminalId - refundMethod type: object properties: &ref_787 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_273 - amount - currency - description - orderId type: object allOf: &ref_274 - required: *ref_217 type: object description: Object that contains details about the transaction. properties: *ref_218 - 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_82 customer: type: object description: Object that contains information about the customer. properties: *ref_267 refundMethod: description: Object that contains information about how the merchant refunds the customer. type: object discriminator: propertyName: type mapping: ach: '#/components/schemas/achPayload' secureToken: '#/components/schemas/secureTokenPayload' oneOf: - required: *ref_162 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_163 - required: *ref_178 type: object writeOnly: true title: Secure token description: Object that contains information about the secure token that represents the customer’s payment details. properties: *ref_179 customFields: type: array description: | Array of customField objects. items: required: *ref_128 type: object properties: *ref_129 examples: bankTransferUnreferencedRefundRequest: summary: Bank Transfer Unreferenced Refund description: Bank Transfer Unreferenced Refund value: &ref_980 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_281 - bankAccount - order - processingTerminalId - refundId - transactionResult type: object properties: &ref_282 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_273 type: object allOf: *ref_274 customer: type: object description: Object that contains information about the customer. properties: *ref_267 bankAccount: description: Object that contains information about the bank account. type: object discriminator: propertyName: type mapping: ach: '#/components/schemas/achBankAccount' pad: '#/components/schemas/padBankAccount' oneOf: - required: *ref_275 type: object title: ACH account description: Object that contains the customer's account details. properties: *ref_276 - required: *ref_277 type: object title: PAD account description: Object that contains the customer's account details. properties: *ref_278 payment: required: *ref_232 type: object description: Object that contains information about a payment. properties: *ref_233 transactionResult: type: object description: Object that contains information about the transaction. required: *ref_279 readOnly: true properties: *ref_280 customFields: type: array description: | Array of customField objects. items: required: *ref_128 type: object properties: *ref_129 examples: bankTransferUnreferencedRefundResponse: summary: Bank Transfer Unreferenced Refund description: Bank Transfer Unreferenced Refund value: &ref_283 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_103 '415': description: Unsupported media type content: *ref_104 '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_489 maxLength: 50 minLength: 4 type: string examples: &ref_490 example: value: '1234001' - name: orderId in: query description: Filter results by the order ID of the refund. schema: &ref_491 maxLength: 24 minLength: 1 type: string examples: &ref_492 example: value: OrderRef6543 - name: nameOnAccount in: query description: Filter results by the accountholder's name. schema: &ref_493 maxLength: 50 minLength: 1 type: string examples: &ref_494 example: value: Sarah%20Hazel%20Hopper - name: last4 in: query description: Filter results by the last four digits of the account number. schema: &ref_495 pattern: '[0-9]{4}' type: string examples: &ref_496 example: value: '7062' - name: type description: Filter results by transaction type. in: query schema: &ref_497 type: array items: type: string enum: - refund - unreferencedRefund examples: &ref_498 example: value: - refund - name: status in: query description: Filter results by the status of the refund. schema: &ref_499 type: array items: type: string enum: - ready - pending - declined - complete - admin - reversal - returned examples: &ref_500 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_501 type: string format: date-time examples: &ref_502 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_503 type: string format: date-time examples: &ref_504 example: value: '2024-07-31T23:59:59Z' - name: settlementState in: query description: Filter results by the settlement status. schema: &ref_505 type: string enum: - settled - unsettled examples: &ref_506 example: value: settled - name: settlementDate in: query description: Filter results by the settlement date. Send a value in **YYYY-MM-DD** format. schema: &ref_507 type: string format: date examples: &ref_508 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_784 - count - data - hasMore - limit type: object allOf: &ref_785 - 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_281 type: object properties: *ref_282 examples: paginatedResults: summary: Paginated Bank Transfer Unreferenced Refund description: Paginated Bank Transfer Unreferenced Refund value: &ref_979 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_284 maxLength: 10 minLength: 10 type: string examples: &ref_285 example: value: CD3HN88U9F responses: '200': description: Successful request. Returns the specific refund. content: application/json: schema: required: *ref_281 type: object properties: *ref_282 examples: bankTransferUnreferencedRefund: summary: Bank Transfer Unreferenced Refund description: Bank Transfer Unreferenced Refund value: *ref_283 '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_284 examples: *ref_285 responses: '200': description: Successful request. We reversed the refund transaction. content: application/json: schema: required: *ref_281 type: object properties: *ref_282 examples: bankTransferUnreferencedRefund: summary: Bank Transfer Unreferenced Refund description: Bank Transfer Unreferenced Refund value: &ref_981 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_103 '415': description: Unsupported media type content: *ref_104 '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_788 - processingTerminalId - bankAccount type: object properties: &ref_789 processingTerminalId: maxLength: 50 minLength: 4 type: string description: Unique identifier that we assigned to the terminal. example: '1234001' bankAccount: description: Object that contains information about the bank account. type: object discriminator: propertyName: type mapping: ach: '#/components/schemas/achPayload' pad: '#/components/schemas/padPayload' oneOf: - required: *ref_162 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_163 - required: *ref_164 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_165 examples: bankAccountVerificationRequestPad: summary: PAD Bank Account Verification Request description: Bank Account Verification Request for PAD value: &ref_982 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_983 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_790 - processingTerminalId - verified type: object properties: &ref_791 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_984 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_103 '415': description: Unsupported media type content: *ref_104 '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/integrate/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_807 - business - processingAccounts properties: &ref_808 business: type: object description: Object that contains information about the business. title: business required: &ref_290 - name - taxId - contactMethods - addresses - organizationType properties: &ref_291 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: Object that contains the addresses for the business. items: oneOf: - title: Legal address required: &ref_794 - type - city - country - address1 - postalCode - state allOf: &ref_795 - type: object description: Type of address. required: &ref_792 - type properties: &ref_793 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 contactMethod objects. One contact method must be an email address. items: discriminator: *ref_2 oneOf: *ref_3 processingAccounts: description: Array of processingAccounts objects. type: array minItems: 1 items: required: &ref_302 - doingBusinessAs - owners - businessType - merchandiseOrServiceSold - businessStartDate - timezone - address - contactMethods - processing - funding - pricing - signature - categoryCode type: object properties: &ref_303 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_298 - 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: 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 contactMethod objects. One contact method must be an email address. 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_299 - transactionAmounts - monthlyAmounts - volumeBreakdown properties: &ref_300 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: - cardPresentKeyed - cardPresentSwiped - mailOrTelephone - ecommerce properties: cardPresentKeyed: description: Estimated percentage of keyed card-present transactions. type: integer format: int32 example: 47 cardPresentSwiped: description: Estimated percentage of swiped card-present transactions. type: integer format: int32 example: 30 mailOrTelephone: description: Estimated percentage of mail order or telephone transactions. type: integer format: int32 example: 3 ecommerce: description: Esimated 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_801 - type: object properties: &ref_301 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: Object that contains HATEOAS links to the pricing information that we apply to the processing account. discriminator: &ref_805 propertyName: type mapping: intent: '#/components/schemas/pricingTemplate' agreement: '#/components/schemas/pricingAgreement' oneOf: &ref_806 - type: object title: Pricing intent required: &ref_802 - type - pricingIntentId properties: &ref_803 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: Pricing agreement allOf: &ref_804 - type: object description: Type of pricing 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_286 properties: *ref_287 signature: type: object description: Object that includes information about how we captured the owner's signature. discriminator: &ref_292 propertyName: type mapping: requestedViaDirectLink: '#/components/schemas/signatureByDirectLink' requestedViaEmail: '#/components/schemas/signatureByEmail' oneOf: &ref_293 - description: Object that contains signature information if we captured the merchant’s signature by direct link. title: Signature by direct link type: object required: &ref_796 - type properties: &ref_797 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: Signature by email type: object required: &ref_798 - type properties: &ref_799 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_312 - type - firstName - lastName - identifiers - contactMethods properties: &ref_313 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_288 type: object title: identifier properties: *ref_289 contactMethods: type: array minItems: 1 maxItems: 4 uniqueItems: true description: | Array of contactMethod objects. **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. 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_986 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: cardPresentKeyed: 47 cardPresentSwiped: 30 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_294 - business - processingAccounts properties: &ref_295 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_290 properties: *ref_291 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/integrate/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: Object that includes information about how we captured the owner's signature. discriminator: *ref_292 oneOf: *ref_293 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_987 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_988 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_306 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_307 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_308 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_309 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_989 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_990 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_800 - 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_294 properties: *ref_295 examples: listMerchantPlatforms: summary: Paginated list of merchant platforms description: Retrieve a list of merchant platforms associated with your account. value: &ref_985 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_296 type: string examples: &ref_297 example: value: '12345' responses: '200': description: Successful request. Returns the merchant platform. content: application/json: schema: type: object title: merchant required: *ref_294 properties: *ref_295 examples: retrievedMerchantPlatforms: summary: Retrieve merchant platform description: Retrieve a merchant platform. value: &ref_991 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_296 examples: *ref_297 - 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_509 type: boolean default: false examples: &ref_510 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_811 - 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_304 - doingBusinessAs - owners - businessType - merchandiseOrServiceSold - timezone - address - contactMethods - processing - funding - pricing - signature - categoryCode type: object properties: &ref_305 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/integrate/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_298 example: America/Chicago maxLength: 28 address: 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 contactMethods objects for the processing account. At least one contactMethod must be an email address. 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_299 properties: *ref_300 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_810 - type: object properties: *ref_301 - 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_809 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: Object that includes information about how we captured the owner's signature. discriminator: *ref_292 oneOf: *ref_293 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_992 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: cardPresentKeyed: 47 cardPresentSwiped: 30 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: cardPresentKeyed: 0 cardPresentSwiped: 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_296 examples: *ref_297 - 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_302 type: object properties: *ref_303 examples: retrievedMerchantPlatforms: summary: Create merchant platform description: Create a merchant platform. value: &ref_993 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: cardPresentKeyed: 47 cardPresentSwiped: 30 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_304 type: object properties: *ref_305 examples: retrievedMerchantPlatforms: summary: Retrieve merchant platform description: Retrieve a merchant platform. value: &ref_994 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: cardPresentKeyed: 47 cardPresentSwiped: 30 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_306 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_307 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_308 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_309 '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_310 type: string examples: &ref_311 example: value: '38765' responses: '200': description: Successful request. Returns the processing account. content: application/json: schema: required: *ref_304 type: object properties: *ref_305 examples: processingAccount: summary: Retrieve processing account description: Retrieve a specific processing account. value: &ref_995 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: cardPresentKeyed: 47 cardPresentSwiped: 30 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: Retrieve a list of funding accounts associated with a processing account. operationId: listProcessingAccountsFundingAccounts parameters: - name: processingAccountId in: path description: Unique identifier that we assigned to the processing account. required: true schema: *ref_310 examples: *ref_311 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_996 - 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_310 examples: *ref_311 - 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_812 - 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_312 properties: *ref_313 examples: paginatedContacts: summary: Paginated list of processing account contacts description: List of contacts associated with a processing account. value: &ref_997 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: Get 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_310 examples: *ref_311 responses: '200': description: Successful request. Returns the pricing agreement for the processing account. 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_823 - country - version - base properties: &ref_824 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_314 required: *ref_315 processor: type: object title: US processor fees description: Object that contains information about U.S. processor fees. properties: card: type: object description: Object that contains the fees for card transactions. 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_316 required: *ref_317 - type: object title: Interchange Plus with three tiers description: Object that contains information about Interchange Plus with three tiers. properties: &ref_817 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: Object that contains the fees for American Express transactions. discriminator: propertyName: type mapping: optBlue: '#/components/schemas/interchangePlusTiered3AmexOptBlue' direct: '#/components/schemas/interchangePlusTiered3AmexDirect' oneOf: - type: object title: American Express OptBlue required: &ref_813 - type - qualifiedRate - midQualRate - nonQualRate properties: &ref_814 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: American Express Direct required: &ref_815 - type - transaction properties: &ref_816 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_818 - planType - fees - type: object title: Tiered pricing with three tiers description: Object that contains information about tiered pricing with three tiers. properties: *ref_318 required: *ref_319 - type: object title: Tiered pricing with four tiers description: Object that contains information about tiered pricing with four tiers. properties: *ref_320 required: *ref_321 - type: object title: Tiered pricing with six tiers description: Object that contains information about tiered pricing with six tiers. properties: *ref_322 required: *ref_323 - type: object title: Flat Rate Plan description: Object that contains information about Flat Rate. properties: *ref_324 required: *ref_325 - type: object title: Consumer Choice Plan description: Object that contains information about ConsumerChoice. properties: *ref_326 required: *ref_327 - type: object title: RewardPay Plan description: Object that contains information about RewardPay. properties: &ref_819 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_820 - planType - fees - type: object title: RewardPayChoice Plan description: Object that contains information about RewardPayChoice. properties: *ref_328 required: *ref_329 ach: type: object description: Object that contains the fees for ACH transactions. properties: *ref_330 gateway: type: object description: Object that contains information about the gateway fees. title: gateway fees properties: &ref_821 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_822 - 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_286 properties: *ref_287 examples: paginatedContacts: summary: Get processing account pricing agreement description: Retrieve a pricing agreement for a processing account. value: &ref_998 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_310 examples: *ref_311 - 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_825 - 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_999 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_310 examples: *ref_311 requestBody: 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_331 - type properties: &ref_332 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_1000 type: pricingAgreement responses: '201': description: Successful request. We sent the email to the merchant. 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_331 properties: *ref_332 examples: reminderCreated: summary: Reminder created description: Reminder created. value: &ref_1001 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_1002 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_1003 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_1004 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/integrate/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_310 examples: *ref_311 requestBody: content: application/json: schema: type: object properties: &ref_836 trainingProvider: type: string description: Indicates who provides training to the merchant for the solution. enum: &ref_333 - 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_334 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_335 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_826 - 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 Batch Close description: Indicates how the merchant batches their transactions. properties: &ref_827 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_828 - batchCloseType - type: object title: Manual Batch Close description: Indicates how the merchant batches their transactions. properties: &ref_829 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_830 - 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_336 - type - solutionTemplateId minItems: 1 maxItems: 20 required: &ref_837 - 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_1006 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_340 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/integrate/event-subscriptions). enum: - open - held - dispatched - fulfilled - cancelled example: open trainingProvider: &ref_834 type: string description: Indicates who provides training to the merchant for the solution. enum: *ref_333 maxLength: 7 default: partner shipping: &ref_835 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_334 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_335 required: *ref_336 - type: object description: Array of links related to your order items. properties: &ref_833 links: type: array items: type: object anyOf: - type: object description: Object that contains information about the processing terminal. properties: &ref_831 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_832 - 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_341 - terminalOrderId - status - orderItems - createdDate - lastModifiedDate examples: terminalOrder: summary: Terminal order description: Terminal order value: &ref_1007 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_337 required: *ref_338 examples: notFound: summary: Not found description: Resource could not be found value: *ref_339 '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_310 examples: *ref_311 - name: status in: query schema: &ref_511 type: string description: Filter terminal orders by status. enum: - open - held - dispatched - fulfilled - cancelled - name: fromDateTime in: query schema: &ref_512 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_513 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_340 required: *ref_341 examples: terminalOrders: summary: Paginated list of Terminal Orders description: Retrieve terminal orders associated with a processing account. value: &ref_1005 - 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_310 examples: *ref_311 - 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_853 - 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_342 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: 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_838 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_839 - gateway - terminalTemplateId batchClosure: description: Object that contains information about when and how the terminal closes the batch. discriminator: propertyName: batchCloseType mapping: automatic: '#/components/schemas/schemas-automaticBatchClose' manual: '#/components/schemas/schemas-manualBatchClose' oneOf: - type: object title: Automatic Batch Close description: Indicates how authorized transactions will be batched for settlement properties: &ref_840 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_841 - batchCloseType - batchCloseTime - type: object title: Manual Batch Close description: Indicates how authorized transactions will be batched for settlement properties: &ref_842 batchCloseType: type: string description: Indicates whether batch settlement of authorized transactions are automatically or manually closed enum: - manual required: &ref_843 - 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: Object that contains the tip settings for the processing terminal. discriminator: propertyName: enabled mapping: 'true': '#/components/schemas/tipProcessingEnabled' 'false': '#/components/schemas/tipProcessingDisabled' anyOf: - type: object description: Tip settings properties: &ref_844 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_845 - enabled - type: object description: Tip settings properties: &ref_846 enabled: type: boolean description: Indicates if the terminal can accept tips. required: &ref_847 - 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: Object that contains details about EBT transactions. 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_848 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_849 - enabled - ebtType - type: object description: Object that contains details about EBT transactions. properties: &ref_850 enabled: type: boolean description: Indicates if the terminal accepts Electronic Benefit Transfer (EBT) transactions. required: &ref_851 - 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/integrate/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_852 - bluetooth - cellular - ethernet - wifi maxLength: 9 required: - manufacturer - model - serialNumber maxItems: 1 minItems: 0 required: &ref_343 - 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_1008 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-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_95 examples: *ref_96 responses: '200': description: Successful request. Returns the processing terminal. content: application/json: schema: type: object properties: *ref_342 required: *ref_343 examples: processingTerminals: summary: Retrieve processing terminal description: Retrieve a specific processing terminal. value: &ref_1009 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_95 examples: *ref_96 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_856 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: Object that contains the host processor configuration. discriminator: propertyName: processor mapping: tsys: '#/components/schemas/tsys' oneOf: - type: object properties: &ref_854 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_855 - processor - merchant - terminal required: &ref_857 - 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_344 type: integer examples: &ref_345 example: value: 1543 responses: '200': description: Successful request. Returns the requested contact. content: application/json: schema: type: object title: contact required: *ref_312 properties: *ref_313 examples: contact: summary: Contact object description: Contact object value: &ref_1010 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_344 examples: *ref_345 requestBody: content: application/json: schema: type: object title: contact required: *ref_312 properties: *ref_313 examples: updateContact: summary: Update contact description: Update a specific contact. value: &ref_1011 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_344 examples: *ref_345 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_514 type: string enum: - registered - suspended - failed examples: &ref_515 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_516 type: string examples: &ref_517 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_862 - 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_346 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 notifications objects. Each object contains information about how we contact you when an event occurs. items: type: object title: Notification method oneOf: &ref_860 - type: object properties: &ref_858 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_859 - type - uri - secret - supportEmailAddress discriminator: &ref_861 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_347 - enabled - eventTypes - notifications examples: paginatedList: summary: Paginated list of Event subscriptions description: Example of a paginated list of event subscriptions value: &ref_1012 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_346 required: *ref_347 examples: createEventSubscription: summary: Create event subscription description: Create an event subscription value: &ref_1013 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: '201': description: Successful request. We created the event subscription. headers: Location: description: URI reference to created resource schema: &ref_1024 type: string content: application/json: schema: type: object title: Event Subscription properties: *ref_346 required: *ref_347 examples: createdEventSubscription: summary: Event subscription created description: Example of a created event subscription. value: &ref_1014 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: 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_518 type: integer format: int32 examples: &ref_519 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_346 required: *ref_347 examples: eventSubscription: summary: Event subscription description: Example of an event subscription. value: &ref_1015 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_346 required: *ref_347 examples: updateEventSubscription: summary: Update event subscription description: Update an event subscription value: &ref_1016 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_100 example: *ref_101 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_1017 - 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_346 required: *ref_347 examples: patchedEventSubscription: summary: Patched event subscription description: Example of a patched event subscription. value: &ref_1018 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/integrate/event-subscriptions). operationId: getTerminalOrder parameters: - name: terminalOrderId in: path description: Unique identifier of the terminal order. required: true schema: &ref_520 type: string examples: &ref_521 example: value: '12345' responses: '200': description: Successful request. Returns the terminal order. content: application/json: schema: type: object properties: *ref_340 required: *ref_341 examples: terminalOrder: summary: Terminal order description: Terminal order value: &ref_1019 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_63 examples: *ref_64 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_348 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_67 example: *ref_68 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_1020 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_69 paginationError: 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 '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_522 type: integer examples: &ref_523 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_348 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_1021 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_524 type: integer examples: &ref_525 example: value: 99 - name: merchantId in: query description: Filter results by the unique identifier that the processor assigned to the merchant. schema: *ref_63 examples: *ref_64 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_865 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_67 example: *ref_68 achDeposit: type: object title: ACH deposit summary description: Object that contains information about the ACH deposit. properties: &ref_863 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_864 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_1022 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_69 paginationError: 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 '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_349 examples: *ref_350 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_351 examples: *ref_352 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_353 examples: *ref_354 instructionId: name: instructionId in: path required: true description: Unique identifier that we assigned to the funding instruction. schema: *ref_355 examples: *ref_356 merchantId: name: merchantId in: query description: Filter results by the unique identifier that the processor assigned to the merchant. schema: *ref_63 examples: *ref_64 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_357 examples: *ref_358 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_359 examples: *ref_360 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_361 examples: *ref_362 batchId: name: batchId in: path required: true description: Unique identifier that we assigned to the batch. style: simple schema: *ref_363 examples: *ref_364 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_72 examples: *ref_73 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_74 examples: *ref_75 transactionType: name: transactionType in: query description: Filter transactions by transaction type. schema: *ref_365 examples: *ref_366 transactionId: name: transactionId description: Unique identifier of the transaction. in: path required: true schema: *ref_367 examples: *ref_368 authorizationId: name: authorizationId description: Unique identifier of the authorization. in: path required: true schema: *ref_369 examples: *ref_370 parameters-date: name: date in: query required: true description: Filter results by the date that the dispute was submitted. schema: *ref_371 examples: *ref_372 disputeId: name: disputeId description: Unique identifier of the dispute. in: path required: true schema: *ref_373 examples: *ref_374 processingTerminalIdPath: name: processingTerminalId in: path required: true description: Unique identifier that we assigned to the terminal. schema: *ref_95 examples: *ref_96 merchantReference: name: merchantReference in: query description: Filter results by the unique identifier that the merchant assigned to the payment link. schema: *ref_375 examples: *ref_376 linkType: name: linkType in: query description: Filter results by the type of link. Send a value of singleUse or multiUse. schema: *ref_377 examples: *ref_378 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_379 examples: *ref_380 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_381 examples: *ref_382 recipientName: name: recipientName in: query description: Filter results by the customer's name. schema: *ref_107 examples: *ref_108 recipientEmail: name: recipientEmail in: query description: Filter results by the customer's email address. schema: *ref_109 examples: *ref_110 createdOn: name: createdOn in: query description: Filter results by the link's created date. Send a value in **YYYY-MM-DD** format. schema: *ref_383 examples: *ref_384 expiresOn: name: expiresOn in: query description: Filter results by the link's expiry date. Send a value in **YYYY-MM-DD** format. schema: *ref_385 examples: *ref_386 paymentLinkId: name: paymentLinkId in: path description: Unique identifier that we assigned to the payment link. required: true schema: *ref_98 examples: *ref_99 paymentPlanId: name: paymentPlanId in: path description: Unique identifier that the merchant assigned to the payment plan. required: true schema: *ref_116 examples: *ref_117 customerName: name: customerName in: query description: Filter by the customer's name. schema: *ref_387 examples: *ref_388 last4: name: last4 in: query description: Filter by the last four digits of the card or account number. schema: *ref_389 examples: *ref_390 paymentPlan: name: paymentPlan in: query description: Filter by the name of the payment plan. schema: *ref_391 examples: *ref_392 frequency: name: frequency in: query description: Filter by the frequency of subscription payments. schema: *ref_393 examples: *ref_394 status: name: status in: query description: Filter by the current status of the subscription. schema: *ref_395 examples: *ref_396 endDate: name: endDate in: query description: | Format: `YYYY-MM-DD` Filter subscriptions that end on a specific date. schema: *ref_397 examples: *ref_398 nextDueDate: name: nextDueDate in: query description: | Format: `YYYY-MM-DD` Filter subscriptions by the date that the next payment is collected. schema: *ref_399 examples: *ref_400 subscriptionId: name: subscriptionId in: path description: Unique identifier that the merchant assigned to the subscription. required: true schema: *ref_134 examples: *ref_135 secureTokenIdInQuery: name: secureTokenId in: query description: Unique identifier that the merchant assigned to the secure token. schema: *ref_401 examples: *ref_402 phone: name: phone in: query description: Filter by the customer's phone number. schema: *ref_403 examples: *ref_404 email: name: email in: query description: Filter by the customer's email address. schema: *ref_405 examples: *ref_406 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_407 examples: *ref_408 first6: name: first6 in: query description: Filter by the first six digits of the card number. schema: *ref_409 examples: *ref_410 secureTokenIdInPath: name: secureTokenId in: path required: true description: Unique identifier that the merchant assigned to the secure token. schema: *ref_160 examples: *ref_161 processingTerminalId: name: processingTerminalId in: path required: true description: Unique identifier that our gateway assigned to the terminal. schema: *ref_411 examples: *ref_412 processingTerminalIdQuery: name: processingTerminalId in: query description: Filter by terminal ID. schema: *ref_234 examples: *ref_235 orderId: name: orderId in: query description: Filter payments by order ID. schema: *ref_413 examples: *ref_414 operator: name: operator in: query description: Filter payments by operator. schema: *ref_415 examples: *ref_416 cardholderName: name: cardholderName in: query description: Filter payments by the cardholder’s name. schema: *ref_417 examples: *ref_418 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_419 examples: *ref_420 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_421 examples: *ref_422 tender: name: tender in: query description: Filter by tender type. schema: *ref_423 examples: *ref_424 tipMode: name: tipMode in: query description: Filter payments by tip. schema: *ref_425 examples: *ref_426 type: name: type in: query description: Filter payments by transaction type. schema: *ref_427 examples: *ref_428 parameters-status: name: status in: query description: Filter payments by the status of the transaction. schema: *ref_429 examples: *ref_430 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_431 examples: *ref_432 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_433 examples: *ref_434 settlementState: name: settlementState in: query description: Filter payments by the settlement status of the transaction. schema: *ref_435 examples: *ref_436 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_437 examples: *ref_438 parameters-paymentLinkId: name: paymentLinkId in: query description: Unique identifier that our gateway assigned to the payment link. schema: *ref_439 examples: *ref_440 paymentId: name: paymentId in: path required: true description: Unique identifier of the payment that the merchant wants to retrieve. schema: *ref_208 examples: *ref_209 serialNumber: name: serialNumber description: Serial number of the merchant’s payment device. in: path required: true schema: *ref_441 examples: *ref_442 paymentInstructionId: name: paymentInstructionId description: Unique identifier that we assigned to the payment instruction. in: path required: true schema: *ref_224 examples: *ref_225 parameters-orderId: name: orderId in: query description: Filter refunds by the unique identifier that the merchant assigned to the order. schema: *ref_443 examples: *ref_444 parameters-operator: name: operator in: query description: Filter refunds by the operator who initiated the request. schema: *ref_445 examples: *ref_446 parameters-cardholderName: name: cardholderName in: query description: Filter refunds by cardholder name. schema: *ref_447 examples: *ref_448 components-parameters-first6: name: first6 in: query description: Filter refunds by the first six digits of the card number. schema: *ref_449 examples: *ref_450 components-parameters-last4: name: last4 in: query description: Filter refunds by the last four digits of the card number. schema: *ref_451 examples: *ref_452 components-parameters-status: name: status in: query description: Filter refunds by the current status of the refund. schema: *ref_453 examples: *ref_454 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_455 examples: *ref_456 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_457 examples: *ref_458 parameters-settlementState: name: settlementState in: query description: Status of the settlement. schema: *ref_459 examples: *ref_460 parameters-settlementDate: name: settlementDate in: query description: Date the transaction was settled. schema: *ref_461 examples: *ref_462 refundId: name: refundId description: Unique identifier that our gateway assigned to the refund. in: path required: true schema: *ref_239 examples: *ref_240 parameters-serialNumber: name: serialNumber description: Serial number that identifies the merchant’s payment device. in: path required: true schema: *ref_463 examples: *ref_464 refundInstructionId: name: refundInstructionId description: Unique identifier that we assigned to the refund instruction. in: path required: true schema: *ref_249 examples: *ref_250 signatureInstructionId: name: signatureInstructionId description: Unique identifier that our gateway assigned to the signature instruction. in: path required: true schema: *ref_253 examples: *ref_254 signatureId: name: signatureId in: path description: Unique identifier that we assigned to the signature. required: true schema: *ref_465 examples: *ref_466 bankTransferPaymentsProcessingTerminalId: name: processingTerminalId in: query required: true description: Filter results by the unique identifier that we assigned to the terminal. schema: *ref_467 examples: *ref_468 bankTransferPaymentsOrderId: name: orderId in: query description: Filter results by the order ID of the payment. schema: *ref_469 examples: *ref_470 bankTransferPaymentsNameOnAccount: name: nameOnAccount in: query description: Filter results by the account holder's name. schema: *ref_471 examples: *ref_472 bankTransferPaymentsLast4: name: last4 in: query description: Filter results by the last four digits of the account number. schema: *ref_473 examples: *ref_474 bankTransferPaymentsType: name: type in: query description: Filter results by transaction type. schema: *ref_475 examples: *ref_476 bankTransferPaymentsStatus: name: status in: query description: Filter results by the status of the payment. schema: *ref_477 examples: *ref_478 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_479 examples: *ref_480 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_481 examples: *ref_482 bankTransferPaymentsSettlementState: name: settlementState in: query description: Filter results by the settlement status. schema: *ref_483 examples: *ref_484 bankTransferPaymentsSettlementDate: name: settlementDate in: query description: Filter results by the settlement date. Send a value in **YYYY-MM-DD** format. schema: *ref_485 examples: *ref_486 components-parameters-paymentLinkId: name: paymentLinkId in: query description: Filter results by the paymentLinkId. schema: *ref_487 examples: *ref_488 bankTransferPaymentsPaymentId: name: paymentId description: Unique identifier that our gateway assigned to the payment. in: path required: true schema: *ref_271 examples: *ref_272 bankTransferRefundProcessingTerminalId: name: processingTerminalId in: query required: true description: Filter results by the unique identifier that we assigned to the terminal. schema: *ref_489 examples: *ref_490 bankTransferRefundOrderId: name: orderId in: query description: Filter results by the order ID of the refund. schema: *ref_491 examples: *ref_492 bankTransferRefundNameOnAccount: name: nameOnAccount in: query description: Filter results by the accountholder's name. schema: *ref_493 examples: *ref_494 bankTransferRefundLast4: name: last4 in: query description: Filter results by the last four digits of the account number. schema: *ref_495 examples: *ref_496 bankTransferRefundType: name: type description: Filter results by transaction type. in: query schema: *ref_497 examples: *ref_498 bankTransferRefundStatus: name: status in: query description: Filter results by the status of the refund. schema: *ref_499 examples: *ref_500 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_501 examples: *ref_502 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_503 examples: *ref_504 bankTransferRefundSettlementState: name: settlementState in: query description: Filter results by the settlement status. schema: *ref_505 examples: *ref_506 bankTransferRefundSettlementDate: name: settlementDate in: query description: Filter results by the settlement date. Send a value in **YYYY-MM-DD** format. schema: *ref_507 examples: *ref_508 bankTransferRefundRefundId: name: refundId description: Unique identifier that our gateway assigned to the refund. in: path required: true schema: *ref_284 examples: *ref_285 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_296 examples: *ref_297 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_509 examples: *ref_510 processingAccountId: name: processingAccountId in: path description: Unique identifier that we assigned to the processing account. required: true schema: *ref_310 examples: *ref_311 processing-accounts-v1_components-parameters-status: name: status in: query schema: *ref_511 fromDateTime: name: fromDateTime in: query schema: *ref_512 toDateTime: name: toDateTime in: query schema: *ref_513 contactId: name: contactId in: path description: Unique identifier for the contact. required: true schema: *ref_344 examples: *ref_345 parameters-v1_components-parameters-status: name: status in: query description: Filter event subscriptions by subscription status. schema: *ref_514 examples: *ref_515 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_516 examples: *ref_517 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_518 examples: *ref_519 terminalOrderId: name: terminalOrderId in: path description: Unique identifier of the terminal order. required: true schema: *ref_520 examples: *ref_521 achDepositId: name: achDepositId description: Unique identifier of the ACH deposit. in: path required: true schema: *ref_522 examples: *ref_523 achDepositIdQuery: name: achDepositId description: Unique identifier of the ACH deposit. You must provide either the 'achDepositId' or the 'date'. in: query schema: *ref_524 examples: *ref_525 schemas: '400': type: object properties: *ref_9 required: *ref_10 '401': type: object properties: *ref_526 required: *ref_527 '403': type: object properties: *ref_528 required: *ref_529 '404': type: object properties: *ref_337 required: *ref_338 '406': type: object properties: *ref_530 required: *ref_531 '409': type: object properties: *ref_27 required: *ref_28 '413': type: object properties: *ref_532 required: *ref_533 '415': type: object properties: *ref_534 required: *ref_535 '500': type: object properties: *ref_536 required: *ref_537 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_538 type: object title: Email contact method properties: *ref_539 contactMethodPhone: required: *ref_540 type: object title: Phone number contact method properties: *ref_541 contactMethodMobile: required: *ref_542 type: object title: Mobile number contact method properties: *ref_543 contactMethodFax: required: *ref_544 type: object title: Fax number contact method properties: *ref_545 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_546 identifier: required: *ref_288 type: object title: identifier properties: *ref_289 ownerRelationship: required: *ref_547 type: object title: Owner relationship description: Object that contains information about the owner's relationship to the business. properties: *ref_548 owner: type: object title: owner required: *ref_30 properties: *ref_31 PaymentMethodAch: type: object title: ACH payment method properties: *ref_549 paymentMethods: uniqueItems: true type: array description: Array of PaymentMethodAch objects. items: *ref_550 example: *ref_551 fundingAccount: required: *ref_20 type: object title: funding account properties: *ref_21 createFundingRecipient: required: *ref_552 type: object title: create funding recipient properties: *ref_553 listFundingAccounts: type: object title: paginated funding accounts allOf: *ref_554 baseIntent: type: object title: base pricing intent description: Object that contains information about the base fees. properties: *ref_555 required: *ref_556 baseUsMonthly: type: object title: Monthly platinum security required: *ref_557 properties: *ref_558 baseUsAnnual: type: object title: Annual platinum security required: *ref_559 properties: *ref_560 baseUs: type: object title: US base fees description: Object that contains information about U.S. base fees. properties: *ref_314 required: *ref_315 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: American Express OptBlue required: *ref_561 properties: *ref_562 interchangePlusAmexDirect: type: object title: American Express Direct required: *ref_563 properties: *ref_564 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_316 required: *ref_317 qualRates: type: object required: *ref_52 properties: *ref_53 interchangePlusPlusAmexOptBlue: type: object title: American Express OptBlue required: *ref_565 properties: *ref_566 interchangePlusPlusAmexDirect: type: object title: American Express Direct required: *ref_567 properties: *ref_568 interchangePlusPlus: type: object title: Interchange Plus Plus description: Object that contains information about Interchange Plus Plus. properties: *ref_569 required: *ref_570 tiered3AmexOptBlue: type: object title: American Express OptBlue required: *ref_571 properties: *ref_572 tiered3AmexDirect: type: object title: American Express Direct required: *ref_573 properties: *ref_574 tiered3: type: object title: Tiered pricing with three tiers description: Object that contains information about tiered pricing with three tiers. properties: *ref_318 required: *ref_319 qualRatesWithPremium: type: object allOf: *ref_54 tiered4AmexOptBlue: type: object title: American Express OptBlue required: *ref_575 properties: *ref_576 tiered4AmexDirect: type: object title: American Express Direct required: *ref_577 properties: *ref_578 tiered4: type: object title: Tiered pricing with four tiers description: Object that contains information about tiered pricing with four tiers. properties: *ref_320 required: *ref_321 qualRatesWithPremiumAndRegulated: type: object allOf: *ref_579 tiered6AmexOptBlue: type: object title: American Express OptBlue required: *ref_580 properties: *ref_581 tiered6AmexDirect: type: object title: American Express Direct required: *ref_582 properties: *ref_583 tiered6: type: object title: Tiered pricing with six tiers description: Object that contains information about tiered pricing with six tiers. properties: *ref_322 required: *ref_323 flatRateAmexDirect: type: object title: American Express Direct required: *ref_584 properties: *ref_585 flatRate: type: object title: Flat Rate Plan description: Object that contains information about Flat Rate. properties: *ref_324 required: *ref_325 consumerChoice: type: object title: Consumer Choice Plan description: Object that contains information about ConsumerChoice. properties: *ref_326 required: *ref_327 rewardPayChoice: type: object title: RewardPayChoice Plan description: Object that contains information about RewardPayChoice. properties: *ref_328 required: *ref_329 ach: type: object description: Object that contains the fees for ACH transactions. properties: *ref_330 gatewayUs5.0: type: object description: Object that contains information about the gateway fees for MPA 5.0. title: gateway fees properties: *ref_586 required: *ref_587 hardwareAdvantagePlan: type: object description: Object that contains information about the Hardware Advantage Plan. properties: *ref_588 required: *ref_589 serviceUs5.0: title: US version 5.0 service type: object description: Object that contains information about the Hardware Advantage Plan. discriminator: *ref_590 oneOf: *ref_591 servicesUs5.0: title: US version 5.0 services array description: Object that contains information about our additional services that the merchant can sign up for. type: array items: *ref_592 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_286 properties: *ref_287 pricingIntent5.0: type: object title: pricing intent version 5.0 description: Object that contains information about a pricing intent for Merchant Processing Agreement (MPA) 5.0. allOf: *ref_593 pricingIntent: type: object title: pricing intent description: Object that contains information about a pricing intent. oneOf: *ref_56 paginatedPricingIntent: type: object title: paginated pricing intents description: Object that contains information about your pricing intents. allOf: *ref_594 patchAdd: type: object title: Patch Add Operation description: A Patch Add Operation. required: *ref_595 properties: *ref_596 patchRemove: type: object title: Patch Remove Operation description: A Patch Remove Operation. required: *ref_597 properties: *ref_598 patchReplace: type: object title: Patch Replace Operation description: A Patch Replace Operation. required: *ref_599 properties: *ref_600 patchMove: type: object title: Patch Move Operation description: A Patch Move Operation. required: *ref_601 properties: *ref_602 patchCopy: type: object title: Patch Copy Operation description: A Patch Copy Operation. required: *ref_603 properties: *ref_604 patchTest: type: object title: Patch Test Operation description: A Patch Test Operation. required: *ref_605 properties: *ref_606 patchDocument: title: Patch Operation description: A JSON Patch operation as defined by RFC 6902. discriminator: *ref_607 oneOf: *ref_608 patchRequest: type: array description: A JSON Patch document as defined by RFC 6902. items: *ref_100 example: *ref_101 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_609 activityRecord: type: object description: Array of activityRecord objects. title: activity record properties: *ref_610 required: *ref_611 merchantSummary: type: object title: merchant summary description: Object that contains information about the merchant. properties: *ref_67 example: *ref_68 batch: type: object title: batch properties: *ref_65 settledSummary: type: object title: settlement summary description: Object that contains information about the settlement. properties: *ref_612 example: *ref_613 batchSummary: type: *ref_76 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_77 cardSummary: type: object title: card summary description: Object that contains information about the card. properties: *ref_78 authorizationSummary: type: object title: authorization summary description: Object that contains information about the authorization. properties: *ref_614 transaction: type: object title: transaction description: Object that contains information about the transaction. properties: *ref_71 transactionSummary: type: object title: transaction summary description: Object that contains summary information about the transaction that the dispute is linked to. properties: *ref_80 authorization: type: object title: authorization description: Object that contains information about the authorization. properties: *ref_79 disputeStatus: type: object title: dispute status description: Object that contains information about the current status of the dispute. properties: *ref_81 dispute: type: object title: dispute description: Object that contains information about the dispute. properties: *ref_615 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_82 promptPaymentLinkCharge: required: *ref_83 type: object title: Prompt amount description: Object that contains information about the charge when the customer enters the amount of the transaction. properties: *ref_84 presetPaymentLinkCharge: required: *ref_85 type: object title: Preset amount description: Object that contains information about the charge when the merchant enters the amount of the transaction. properties: *ref_86 multiUsePaymentLinkOrder: required: *ref_616 type: object description: Object that contains information about the order. properties: *ref_617 customLabel: type: object description: Object that contains the information for the custom label. properties: *ref_87 paymentLinkAssets: required: *ref_88 type: object readOnly: true description: Object that contains shareable assets for the payment link. properties: *ref_89 credentialOnFile: type: object description: Object that contains information about saving the customer’s payment details. properties: *ref_90 multiUsePaymentLink: required: *ref_91 type: object title: Multi-use link description: Object that contains information about a multi-use payment link. properties: *ref_92 singleUsePaymentLinkOrder: required: *ref_618 type: object description: Object that contains information about the order. properties: *ref_619 singleUsePaymentLink: required: *ref_93 type: object title: Single-use link description: Object that contains information about a single-use payment link. properties: *ref_94 paymentLinkPaginatedList: required: *ref_620 type: object allOf: *ref_621 paymentLinkEmailRecipient: required: *ref_622 type: object description: Object that contains the contact details of the recipient. properties: *ref_623 paymentLinkEmailShareEvent: required: *ref_105 type: object title: Share via email description: Object that contains the information about a sharing event that the merchant sent by email. properties: *ref_106 sharingEventPaginatedList: required: *ref_624 type: object allOf: *ref_625 paymentPlanBase: required: *ref_626 type: object properties: *ref_627 paymentPlanSetupOrderBase: type: object description: Object that contains information about the initial cost that a customer pays to set up the subscription. properties: *ref_628 paymentPlanOrderBreakdownBase: required: *ref_629 type: object description: | Object that contains information about the taxes that apply to the transaction. properties: *ref_630 retrievedTax: required: *ref_123 type: object properties: *ref_124 paymentPlanOrderBreakdown: required: *ref_111 type: object allOf: *ref_112 paymentPlanSetupOrder: type: object allOf: *ref_631 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_632 paymentPlanRecurringOrder: type: object allOf: *ref_633 paymentPlan: required: *ref_113 type: object allOf: *ref_114 paymentPlanPaginatedList: required: *ref_634 type: object allOf: *ref_635 paymentPlanSummary: required: *ref_636 type: object properties: *ref_637 secureTokenSummary: required: *ref_137 type: object description: Object that contains information about the secure token. properties: *ref_138 subscriptionPaymentOrderBase: description: Object that contains information about the initial cost that a customer pays to set up the subscription. type: object properties: *ref_120 convenienceFee: required: *ref_171 type: object readOnly: true description: Object that contains information about the convenience fee for the transaction. properties: *ref_172 subscriptionOrderBreakdownBase: required: *ref_121 type: object properties: *ref_122 surcharge: type: object description: | Object that contains information about the surcharge. properties: *ref_168 subscriptionOrderBreakdown: required: *ref_126 type: object description: | Object that contains information about the surcharge and taxes that apply to the transaction. allOf: *ref_127 subscriptionPaymentOrder: type: object allOf: *ref_136 subscriptionRecurringOrderBase: type: object properties: *ref_125 subscriptionRecurringOrder: type: object description: | Object that contains information about the cost of each payment. allOf: *ref_638 subscriptionState: required: *ref_139 type: object description: A snapshot of the subscription's current state. properties: *ref_140 customField: required: *ref_128 type: object properties: *ref_129 subscription: required: *ref_130 type: object properties: *ref_131 subscriptionPaginatedList: required: *ref_639 type: object allOf: *ref_640 secureTokenPayload: required: *ref_178 type: object writeOnly: true title: Secure token description: Object that contains information about the secure token that represents the customer’s payment details. properties: *ref_179 taxRate: type: object required: *ref_169 properties: *ref_170 subscriptionOrderBreakdownRequest: required: *ref_118 type: object description: | Object that contains information about the taxes to apply to the transaction. allOf: *ref_119 subscriptionPaymentOrderRequest: type: object allOf: *ref_641 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_642 subscriptionRequest: required: *ref_643 type: object properties: *ref_644 subscriptionPaymentRequest: required: *ref_645 properties: *ref_646 paymentSummary: required: *ref_232 type: object description: Object that contains information about a payment. properties: *ref_233 subscriptionPayment: required: *ref_647 type: object properties: *ref_648 retrievedAddress: type: object title: address description: Object that contains information about the address. properties: *ref_149 retrievedShipping: description: Object that contains information about the customer and their shipping address. type: object properties: *ref_649 retrievedCustomer: type: object description: Object that contains the customer's contact details and address information. properties: *ref_192 achSource: required: *ref_152 type: object title: ACH account description: Object that contains the customer's account details. properties: *ref_153 padSource: required: *ref_154 type: object title: PAD account description: Object that contains the customer's account details. properties: *ref_155 surcharging: required: *ref_259 type: object description: Object that contains surcharge information. Our gateway returns this object only if the merchant adds a surcharge to transactions. properties: *ref_260 cardSource: required: *ref_156 type: object title: Card description: Object that contains the customer's card details. properties: *ref_157 secureToken: required: *ref_150 type: object description: Object that contains information about the secure token. properties: *ref_151 achSourceWithAccountType: allOf: *ref_650 padSourceWithAccountType: allOf: *ref_651 secureTokenWithAccountType: allOf: *ref_158 secureTokenPaginatedListWithAccountType: required: *ref_652 type: object allOf: *ref_653 shipping: description: Object that contains information about the customer and their shipping address. type: object properties: *ref_212 customer: type: object description: Object that contains the customer's contact details and address information. properties: *ref_175 ipAddress: required: *ref_176 type: object writeOnly: true description: Object that contains the IP address of the device that sent the request. properties: *ref_177 achPayload: required: *ref_162 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_163 padPayload: required: *ref_164 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_165 deviceConfig: required: *ref_654 type: object description: Object that contains information about the configuration of the POS terminal. properties: *ref_655 device: required: *ref_141 type: object description: Object that contains information about the physical device the merchant used to capture the customer’s card details. properties: *ref_142 rawCardDetails: required: *ref_656 type: object title: Raw description: Object that contains information about the unencrypted card details. properties: *ref_657 encryptionCapableDevice: required: *ref_143 type: object description: Object that contains information about the encryption details of the POS terminal. allOf: *ref_144 ebtDetails: type: object required: *ref_220 description: Object that contains information about the Electronic Benefit Transfer (EBT) transaction. properties: *ref_221 voucher: required: *ref_658 type: object description: | Object that contains information about the EBT voucher. **Note:** Vouchers are available only for EBT SNAP payments. properties: *ref_659 ebtDetailsWithVoucher: type: object required: *ref_145 description: Object that contains information about the Electronic Benefit Transfer (EBT) transaction. allOf: *ref_146 iccCardDetails: required: *ref_660 type: object title: Chip description: Object that contains information about the Integrated Circuit Card (ICC). properties: *ref_661 fullyEncryptedKeyedDataFormat: required: *ref_662 type: object title: Encrypted description: Object that contains information about the encrypted card data for keyed transactions. properties: *ref_663 partiallyEncryptedKeyedDataFormat: required: *ref_664 type: object title: Partially encrypted description: Object that contains information about the partially-encrypted card data for keyed transactions. properties: *ref_665 plainTextKeyedDataFormat: required: *ref_666 type: object title: Unencrypted description: Object that contains information about the plain-text card data for keyed transactions. properties: *ref_667 dukptPinDetails: required: *ref_147 type: object title: Encrypted description: Object that contains information about encrypted PIN details. properties: *ref_148 keyedCardDetails: required: *ref_668 type: object title: Keyed description: Object that contains information about the keyed card details. properties: *ref_669 encryptedSwipedDataFormat: required: *ref_670 type: object title: Encrypted description: Object that contains information about the encrypted swiped card data. properties: *ref_671 plainTextSwipedDataFormat: required: *ref_672 type: object title: Unencrypted description: Object that contains information about plain-text swiped card data. properties: *ref_673 swipedCardDetails: required: *ref_674 type: object title: Swiped description: Object that contains information about the customer’s card details for swiped transactions. properties: *ref_675 cardPayload: required: *ref_166 type: object writeOnly: true title: Card description: Object that contains information about the customer’s payment card. properties: *ref_167 rawPinDetails: required: *ref_676 type: object title: Unencrypted description: Object that contains information about the unencrypted PIN details. properties: *ref_677 singleUseTokenPayload: required: *ref_180 type: object writeOnly: true title: Single-use token description: Object that contains information about the single-use token, which represents the customer’s payment details. properties: *ref_181 gatewayThreeDSecure: required: *ref_182 type: object title: Gateway description: Object that contains the 3-D Secure information from our gateway. properties: *ref_183 thirdPartyThreeDSecure: required: *ref_184 type: object title: Third party description: Object that contains the 3-D Secure information from a third party. properties: *ref_185 tokenizationRequest: required: *ref_678 type: object properties: *ref_679 singleUseTokenAccountUpdate: required: *ref_680 type: object description: Object that contains the token. properties: *ref_681 accountUpdate: description: Object that contains the single-use token. discriminator: *ref_682 oneOf: *ref_683 singleUseTokenRequest: required: *ref_684 type: object properties: *ref_685 singleUseToken: required: *ref_686 type: object properties: *ref_687 hostedFieldsCreateSessionRequest: required: *ref_688 type: object title: Hosted Fields Initialization description: Object that contains information about Hosted Fields initialization request. properties: *ref_689 hostedFieldsCreateSessionResponse: required: *ref_690 type: object properties: *ref_691 applePaySessions: required: *ref_692 type: object properties: *ref_693 applePayResponseSession: required: *ref_694 type: object properties: *ref_695 order: required: *ref_217 type: object description: Object that contains details about the transaction. properties: *ref_218 dccOffer: required: *ref_226 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_227 firstTxnReferenceData: type: object description: Object that contains information about the initial payment for the payment instruction. properties: *ref_696 standingInstructions: required: *ref_697 type: object description: If you don't use our Subscriptions mechanism, include this section to configure your standing/recurring orders. properties: *ref_698 paymentOrderBase: required: *ref_186 type: object description: Object that contains information about the payment. allOf: *ref_187 tip: required: *ref_210 type: object description: Object that contains information about the tip. properties: *ref_211 choiceRate: required: *ref_699 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_700 dualPricing: required: *ref_701 type: object description: Object that contains information about dual pricing. properties: *ref_702 breakdownBase: required: *ref_188 type: object description: Object that contains information about the breakdown of the transaction. properties: *ref_189 breakdown: type: object allOf: *ref_703 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_704 lineItemBase: required: *ref_190 type: object description: List of line items. properties: *ref_191 lineItem: type: object allOf: *ref_705 itemizedBreakdown: required: *ref_706 type: object description: Object that contains information about the breakdown of the transaction. allOf: *ref_707 paymentOrder: type: object description: Object that contains information about the payment. allOf: *ref_193 securityCheck: type: object description: Object that contains information about card verification and security checks. properties: *ref_194 emvTag: required: *ref_195 type: object description: Object that contains information about the EMV tag. properties: *ref_196 cardBalance: required: *ref_197 type: object description: Object that contains information about the total funds available in the card. properties: *ref_198 retrievedCard: required: *ref_230 type: object description: Object that contains the details of the payment card. properties: *ref_231 refundSummary: required: *ref_199 type: object description: Object that contains information about a refund. properties: *ref_200 supportedOperations: type: array items: *ref_201 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_202 transactionResult: required: *ref_203 type: object properties: *ref_204 description: Object that contains information about the transaction response details. retrievedPayment: required: *ref_205 type: object properties: *ref_206 paymentPaginatedListForRead: required: *ref_708 type: object allOf: *ref_709 taxAmount: type: object required: *ref_710 properties: *ref_711 tax: type: object description: Object that contains information about the tax details. discriminator: *ref_173 oneOf: *ref_174 breakdownRequest: type: object allOf: *ref_712 lineItemRequest: type: object allOf: *ref_713 itemizedBreakdownRequest: required: *ref_215 type: object description: Object that contains information about the breakdown of the transaction. allOf: *ref_216 paymentOrderRequest: type: object description: Object that contains information about the payment. allOf: *ref_714 digitalWalletPayload: required: *ref_257 type: object writeOnly: true title: Digital wallet description: Object that contains information about the payment details in the customer’s digital wallet. properties: *ref_258 schemas-credentialOnFile: type: object description: Object that contains information about saving the customer’s payment details. properties: *ref_219 offlineProcessing: required: *ref_715 type: object description: Object that contains information about the transaction if the merchant ran it when the terminal was offline. properties: *ref_716 paymentRequest: required: *ref_717 type: object properties: *ref_718 card: required: *ref_255 type: object description: Object that contains the details of the payment card. properties: *ref_256 payment: required: *ref_213 type: object properties: *ref_214 breakdownAdjustment: type: object description: Object that contains information about the tip amount of a transaction. properties: *ref_719 orderAdjustment: required: *ref_720 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_721 statusAdjustment: required: *ref_241 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_242 customerAdjustment: required: *ref_243 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_244 signatureAdjustment: required: *ref_722 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_723 paymentAdjustment: required: *ref_724 type: object description: Object that contains the transaction adjustment object. properties: *ref_725 paymentCapture: description: Object that contains the details of the payment that the merchant wants to capture. type: object properties: *ref_726 paymentReversal: type: object properties: *ref_727 referencedRefund: description: Object that contains the details of the payment that the merchant wants to refund. required: *ref_728 type: object properties: *ref_729 breakdownForPaymentInstructions: type: object allOf: *ref_730 paymentInstructionOrder: required: *ref_731 type: object description: Object that contains information about the payment. allOf: *ref_732 customizationOptions: type: object description: Object that contains available options to customize certain aspects of an instruction. properties: *ref_245 paymentInstructionRequest: required: *ref_733 type: object description: Object that contains the instructions for initiating a payment on a physical device. properties: *ref_734 deviceInstruction: type: object description: Object that contains information about the status of the instruction properties: *ref_246 paymentInstruction: required: *ref_222 type: object allOf: *ref_223 refundOrder: required: *ref_228 type: object description: Object that contains information about the refund. allOf: *ref_229 retrievedRefund: required: *ref_236 type: object description: Object that contains information about the retrieved refund. properties: *ref_237 refundPaginatedList: required: *ref_735 type: object description: Object that contains information about refund objects. allOf: *ref_736 unreferencedRefund: required: *ref_737 type: object description: Refund a payment that is not linked to a previous transaction. Unreferenced refunds are available only on certain accounts. properties: *ref_738 refundAdjustment: required: *ref_739 type: object description: Object that contains information about the adjustment to the refund. properties: *ref_740 refundInstructionOrder: required: *ref_741 type: object description: Object that contains information about the refund. allOf: *ref_742 refundInstructionRequest: required: *ref_743 type: object description: Object that contains information about the instruction request to initiate a refund on a payment device. properties: *ref_744 refundInstruction: required: *ref_247 type: object allOf: *ref_248 signatureInstructionRequest: required: *ref_745 type: object description: Object that contains the instructions for capturing a signature on a physical device. properties: *ref_746 signatureInstruction: required: *ref_251 type: object allOf: *ref_252 cardVerificationRequest: required: *ref_747 type: object properties: *ref_748 cardVerificationResult: required: *ref_749 type: object properties: *ref_750 balanceInquiry: required: *ref_751 type: object properties: *ref_752 balance: required: *ref_753 type: object properties: *ref_754 cardBinPayload: required: *ref_755 type: object writeOnly: true title: Card BIN description: Object that contains information about the card's bank identification number (BIN). properties: *ref_756 binLookup: required: *ref_757 type: object properties: *ref_758 cardInfo: required: *ref_261 type: object readOnly: true properties: *ref_262 description: Object that contains information about the card. fxRateInquiry: required: *ref_759 type: object properties: *ref_760 fxRateInquiryResult: required: *ref_761 type: object description: Object that indicates if the customer's card is eligible for Dynamic Currency Conversion (DCC). properties: *ref_762 fxRate: required: *ref_763 type: object description: Foreign exchange rate for the transaction. properties: *ref_764 bankTransferPaymentOrderBase: required: *ref_263 type: object allOf: *ref_264 description: Object that contains information about the transaction. bankTransferBreakdownBase: required: *ref_265 type: object description: Object that contains information about the transaction. properties: *ref_266 bankTransferBreakdown: allOf: *ref_765 required: *ref_766 type: object description: Object that contains information about the transaction. properties: *ref_767 bankTransferPaymentOrder: required: *ref_768 type: object allOf: *ref_769 description: Object that contains information about the transaction. bankTransferCustomer: type: object description: Object that contains information about the customer. properties: *ref_267 achBankAccount: required: *ref_275 type: object title: ACH account description: Object that contains the customer's account details. properties: *ref_276 padBankAccount: required: *ref_277 type: object title: PAD account description: Object that contains the customer's account details. properties: *ref_278 bankTransferReturnSummary: required: *ref_770 type: object description: Object that contains information about a return. properties: *ref_771 bankTransferResult: type: object description: Object that contains information about the transaction. required: *ref_279 readOnly: true properties: *ref_280 bankTransferPayment: required: *ref_268 type: object description: Object that contains information about the sale and the customer's bank details. properties: *ref_269 bankTransferPaymentPaginatedList: required: *ref_772 type: object allOf: *ref_773 bankTransferRequestBreakdown: allOf: *ref_774 required: *ref_775 type: object description: Object that contains information about the transaction. properties: *ref_776 bankTransferPaymentRequestOrder: required: *ref_777 type: object allOf: *ref_778 description: Object that contains information about the transaction. bankTransferPaymentRequest: required: *ref_779 type: object description: Object that contains information about the sale and the customer's bank details. properties: *ref_780 bankTransferReferencedRefund: required: *ref_781 type: object description: Object that contains information about the payment that you want to refund. properties: *ref_782 representment: type: object description: Object that contains the paymentMethod object. properties: *ref_783 bankTransferRefundOrder: description: Object that contains information about the order. required: *ref_273 type: object allOf: *ref_274 bankTransferRefund: required: *ref_281 type: object properties: *ref_282 bankTransferRefundPaginatedList: required: *ref_784 type: object allOf: *ref_785 bankTransferUnreferencedRefund: required: *ref_786 type: object properties: *ref_787 bankAccountVerificationRequest: required: *ref_788 type: object properties: *ref_789 bankAccountVerificationResult: required: *ref_790 type: object properties: *ref_791 addressType: type: object description: Type of address. required: *ref_792 properties: *ref_793 legalAddress: title: Legal address required: *ref_794 allOf: *ref_795 business: type: object description: Object that contains information about the business. title: business required: *ref_290 properties: *ref_291 signatureByDirectLink: description: Object that contains signature information if we captured the merchant’s signature by direct link. title: Signature by direct link type: object required: *ref_796 properties: *ref_797 signatureByEmail: description: Object that contains signature information if we captured the merchant’s signature by email. title: Signature by email type: object required: *ref_798 properties: *ref_799 signature: type: object description: Object that includes information about how we captured the owner's signature. discriminator: *ref_292 oneOf: *ref_293 merchantPlatform: type: object title: merchant required: *ref_294 properties: *ref_295 paginatedMerchants: type: object title: paginated merchant platforms allOf: *ref_800 timezone: description: Time zone for the processing account. enum: *ref_298 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_299 properties: *ref_300 commonFunding: type: object properties: *ref_301 createFunding: type: object description: | Object that contains information about the funding schedule of the processing account. allOf: *ref_801 pricingTemplate: type: object title: Pricing intent required: *ref_802 properties: *ref_803 pricingAgreement: type: object title: Pricing agreement allOf: *ref_804 pricing: type: object description: Object that contains HATEOAS links to the pricing information that we apply to the processing account. discriminator: *ref_805 oneOf: *ref_806 contact: type: object title: contact required: *ref_312 properties: *ref_313 createProcessingAccount: required: *ref_302 type: object properties: *ref_303 createMerchantAccount: type: object title: create merchant platform required: *ref_807 properties: *ref_808 fundingAccountSummary: type: object title: funding account summary properties: *ref_809 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_810 processingAccount: required: *ref_304 type: object properties: *ref_305 paginatedProcessingAccounts: type: object title: paginated processing accounts allOf: *ref_811 paginatedContacts: type: object title: paginated Contacts allOf: *ref_812 interchangePlusTiered3AmexOptBlue: type: object title: American Express OptBlue required: *ref_813 properties: *ref_814 interchangePlusTiered3AmexDirect: type: object title: American Express Direct required: *ref_815 properties: *ref_816 interchangePlusTiered3: type: object title: Interchange Plus with three tiers description: Object that contains information about Interchange Plus with three tiers. properties: *ref_817 required: *ref_818 rewardPay: type: object title: RewardPay Plan description: Object that contains information about RewardPay. properties: *ref_819 required: *ref_820 gatewayUs: type: object description: Object that contains information about the gateway fees. title: gateway fees properties: *ref_821 required: *ref_822 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_823 properties: *ref_824 paginatedOwners: type: object title: paginated Owners allOf: *ref_825 pricingAgreementReminder: description: Object that contains information about the pricing agreement reminder. type: object required: *ref_331 properties: *ref_332 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_826 example: America/Chicago maxLength: 28 automaticBatchClose: type: object title: Automatic Batch Close description: Indicates how the merchant batches their transactions. properties: *ref_827 required: *ref_828 manualBatchClose: type: object title: Manual Batch Close description: Indicates how the merchant batches their transactions. properties: *ref_829 required: *ref_830 orderItem: type: object properties: *ref_335 required: *ref_336 processingTerminalSummary: type: object description: Object that contains information about the processing terminal. properties: *ref_831 required: *ref_832 links: type: object description: Array of links related to your order items. properties: *ref_833 terminalOrder: type: object properties: *ref_340 required: *ref_341 trainingProvider: *ref_834 properties-shipping: *ref_835 createTerminalOrder: type: object properties: *ref_836 required: *ref_837 payrocGateway: type: object description: Object that contains the gateway settings for the solution. properties: *ref_838 required: *ref_839 schemas-automaticBatchClose: type: object title: Automatic Batch Close description: Indicates how authorized transactions will be batched for settlement properties: *ref_840 required: *ref_841 schemas-manualBatchClose: type: object title: Manual Batch Close description: Indicates how authorized transactions will be batched for settlement properties: *ref_842 required: *ref_843 tipProcessingEnabled: type: object description: Tip settings properties: *ref_844 required: *ref_845 tipProcessingDisabled: type: object description: Tip settings properties: *ref_846 required: *ref_847 ebtEnabled: type: object description: Object that contains details about EBT transactions. properties: *ref_848 required: *ref_849 ebtDisabled: type: object description: Object that contains details about EBT transactions. properties: *ref_850 required: *ref_851 communicationType: type: string description: Indicates how the device communicates with its host. enum: *ref_852 maxLength: 9 processingTerminal: type: object properties: *ref_342 required: *ref_343 paginatedProcessingTerminals: type: object title: paginated Processing Terminals allOf: *ref_853 tsys: type: object properties: *ref_854 required: *ref_855 hostConfiguration: type: object description: Object that contains the terminal's host configuration. properties: *ref_856 required: *ref_857 webhook: type: object properties: *ref_858 required: *ref_859 notification: type: object title: Notification method oneOf: *ref_860 discriminator: *ref_861 eventSubscription: type: object title: Event Subscription properties: *ref_346 required: *ref_347 paginatedEventSubscriptions: type: object title: paginated event subscriptions allOf: *ref_862 achDeposit: type: object title: ACH deposit description: Object that contains information about the ACH deposit. properties: *ref_348 achDepositSummary: type: object title: ACH deposit summary description: Object that contains information about the ACH deposit. properties: *ref_863 example: *ref_864 achDepositFee: type: object title: ACH deposit fee description: Object that contains information about the ACH deposit fee. properties: *ref_865 examples: paginatedFundRecipients: summary: Paginated funding recipients. description: Paginated list of funding recipients. value: *ref_866 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_867 forbidden: summary: Forbidden description: You do not have the required permission value: *ref_868 apiError: summary: Api error description: Unable to process your request. value: *ref_869 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_870 idempotentKeyInUse: summary: Idempotency key in use description: Idempotency key in use value: *ref_29 fundingRecipient: summary: Funding recipient. description: Funding recipients. value: *ref_871 notFound: summary: Not found description: Resource could not be found value: *ref_339 fundingAccounts: summary: List of funding accounts description: List of funding accounts. value: *ref_872 fundingAccount: summary: Funding account description: Funding accounts. value: *ref_873 listFundingAccountExample: summary: Paginated funding accounts value: *ref_874 noResults: summary: No results found description: No results found value: *ref_875 fundingAccountExample: summary: Masked funding account example. value: *ref_876 retrievedOwner: summary: Retrieve owner description: Retrieve a specific owner. value: *ref_877 updateOwner: summary: Update owner description: Update a specific owner. value: *ref_878 paginatedPricingIntent: summary: Paginated pricing intent description: Example of a paginated pricing intent. value: *ref_879 interchangePlus: summary: Interchange Plus description: Create a pricing intent. value: *ref_880 interchangePlusPlus: summary: Interchange Plus Plus description: Create a pricing intent. value: *ref_881 tiered3: summary: Tiered 3 description: Create a pricing intent. value: *ref_882 tiered4: summary: Tiered 4 description: Create a pricing intent. value: *ref_883 tiered6: summary: Tiered 6 description: Create a pricing intent. value: *ref_884 flatRate: summary: Flat Rate description: Create a pricing intent. value: *ref_885 consumerChoice: summary: Consumer Choice description: Create a pricing intent. value: *ref_886 rewardPayChoice: summary: Reward Pay Choice description: Create a pricing intent. value: *ref_887 pricingIntent: summary: Pricing intent description: Pricing intent value: *ref_57 modifyPricingIntent: summary: Create pricing intent description: Create a pricing intent. value: *ref_888 patchPricingIntentRealistic: summary: Partially update pricing intent description: | Partially update an existing pricing intent. Structure your request to follow the RFC 6902 standard. value: *ref_889 patchOperations: summary: Example patch operations that apply the RFC 6902 standard description: | Example patch operations that apply the RFC 6902 standard. value: *ref_102 listInstructionsExample: summary: Paginated instructions list value: *ref_890 parameterError: summary: Bad request description: One or more validation errors occurred. value: *ref_891 paginationError: summary: Bad request description: One or more validation errors occurred value: *ref_892 outsideRecordRange: summary: Bad request description: Requested data outside allowed range. value: *ref_893 newInstructionAccepted: summary: New instruction accepted. value: *ref_894 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 instructionIdError: summary: Bad request description: One or more validation errors occurred. value: *ref_60 canNotBeModified: summary: Cannot be modified description: Resource cannot be modified. value: *ref_62 listBalancesExample: summary: Paginated list of merchant balances description: Paginated list of merchant balances. value: *ref_895 paginatedList: summary: Paginated activity records description: Valid payfac account with activity for date range. value: *ref_896 examples-parameterError: summary: Bad request description: One or more validation errors occurred. value: *ref_897 paginatedBatches: summary: Paginated batches value: *ref_898 components-examples-parameterError: summary: Bad Request description: One or more validation errors occurred value: *ref_69 examples-paginationError: summary: Bad Request description: One or more validation errors occurred value: *ref_70 batchIdError: summary: Bad Request description: One or more validation errors occurred value: *ref_66 paginatedTransactions: summary: Paginated transactions value: *ref_899 transactionIdError: summary: Bad Request description: One or more validation errors occurred value: *ref_900 paginatedAuthorizations: summary: Paginated authorizations value: *ref_901 paginatedDisputes: summary: Paginated disputes value: *ref_902 paginatedPaymentLinks: summary: Payment links description: Paginated list of payment links value: *ref_903 multiUsePaymentLinkRequest: summary: Multi-use payment link. description: Create a multi-use payment link. value: *ref_904 singleUsePaymentLinkRequest: summary: Single-use payment link. description: Create a single-use payment link. value: *ref_905 paymentLinkResponse: summary: Payment Link description: Active multi-use payment link. value: *ref_97 resourceExists: summary: Resource already exists description: Resource already exists value: *ref_906 unsupportedMediaType: summary: Unsupported media type description: The payload is in an unsupported format. value: *ref_907 patchPaymentLinkRealistic: summary: Partially update payment link description: | Partially update an existing payment link. Structure your request to follow the RFC 6902 standard. value: *ref_908 deactivatedPaymentLink: summary: Payment link description: Deactivated multi-use payment link. value: *ref_909 paginatedSharingEvents: summary: Sharing events description: Paginated list of payment link sharing events value: *ref_910 sharePaymentLinkRequest: summary: Share a payment link. description: Share a payment link. value: *ref_911 paymentLinkShareEvent: summary: Payment link sharing event. description: Payment link sharing event value: *ref_912 paginatedPaymentPlan: summary: Payment Plan description: Payment Plan value: *ref_913 paymentPlanRequest: summary: Payment Plan description: Payment Plan value: *ref_914 paymentPlanResponse: summary: Payment Plan description: Payment Plan value: *ref_115 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_915 paginatedSubscription: summary: Paginated Subscription description: Example of Paginated Subscription value: *ref_916 subscriptionRequest: summary: Subscription description: Subscription value: *ref_917 subscriptionWithSurchargeResponse: summary: Subscription with surcharge description: Subscription with surcharge value: *ref_132 subscriptionWithConvenienceFeeResponse: summary: Subscription with convenience fee description: Subscription with convenience fee value: *ref_133 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_918 deactivateSubscription: summary: Deactivate subscription description: Deactivate a subscription value: *ref_919 subscriptionPaymentRequest: summary: Subscription manual payment description: Subscription manual payment value: *ref_920 subscriptionPaymentResponse: summary: Subscription manual payment description: Subscription manual payment value: *ref_921 paginatedSecureToken: summary: Paginated Secure Token description: Paginated Secure Token value: *ref_922 secureTokenRequest: summary: Secure Token description: Secure Token value: *ref_923 secureTokenResponse: summary: Secure Token description: Secure Token value: *ref_159 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_924 accountUpdateRequest: summary: Update account details description: Account update request by single use token value: *ref_925 payloadTooLarge: summary: Payload too large description: The payload submitted is too large value: *ref_926 singleUseTokenRequest: summary: Create single-use token description: Create a single-use token. The token expires after 30 minutes. value: *ref_927 singleUseTokenResponse: summary: Create single-use token description: Create a single-use token. The token expires after 30 minutes. value: *ref_928 createSessionRequest: summary: Create session request description: Create session request. value: *ref_929 createSessionResponse: summary: Create session response description: Create session response. value: *ref_930 applePaySessions: summary: Apple Pay session description: Start a session with Apple to accept a payment with Apple Pay. value: *ref_931 applePayResponseSession: summary: Apple Pay session response description: Wrapper for the content that Apple returns after starting the Apple Pay session. value: *ref_932 paginatedPayment: summary: Payment description: Payment value: *ref_933 paymentRequest: summary: Card Payment description: Payment value: *ref_934 applePaySaleRequest: summary: Apple Pay Payment value: *ref_935 paymentResponse: summary: Payment description: Payment value: *ref_207 applePaySaleResponse: summary: Apple Pay Payment value: *ref_936 adjustPaymentRequest: summary: Adjust Payment description: Adjust Payment value: *ref_937 adjustPaymentResponse: summary: Adjust Payment description: Adjust Payment value: *ref_938 paymentCaptureRequest: summary: Payment capture description: Capture a payment with itemized breakdown value: *ref_939 reversalPaymentRequest: summary: Reversal Payment description: Reversal Payment value: *ref_940 reversalPaymentResponse: summary: Reversal Payment description: Reversal Payment value: *ref_941 refundPaymentRequest: summary: Refund Payment description: Refund Payment value: *ref_942 refundPaymentResponse: summary: Refund Payment description: Refund Payment value: *ref_943 paymentInstructionRequest: summary: Payment Instruction description: Submit an instruction for initiating a payment on a physical device. value: *ref_944 paymentInstructionInProgress: summary: Payment instruction description: Object that contains information about the progress of the payment instruction. value: *ref_945 paymentInstruction: summary: Payment instruction description: Object that contains information about the progress of the payment instruction. value: *ref_946 paymentInstructionCompleted: summary: Payment instruction already completed description: Payment instruction already completed value: *ref_947 paymentInstructionFailed: summary: Payment instruction failed description: Payment instruction failed value: *ref_948 paginatedRefund: summary: Paginated Refund description: Paginated Refund value: *ref_949 refundRequest: summary: Refund description: Refund value: *ref_950 refundResponse: summary: Refund description: Refund value: *ref_238 adjustRefundRequest: summary: Adjust Refund description: Adjust Refund value: *ref_951 adjustRefundResponse: summary: Adjust Refund description: Adjust Refund value: *ref_952 reverseRefund: summary: Reverse Refund description: Reverse Refund value: *ref_953 refundInstructionRequest: summary: Refund instruction description: Submit an instruction for initiating a refund on a physical device. value: *ref_954 refundInstructionInProgress: summary: Refund instruction description: Object that contains information about the progress of the refund instruction. value: *ref_955 refundInstruction: summary: Refund instruction description: Object that contains information about the progress of the refund instruction. value: *ref_956 refundInstructionCompleted: summary: Refund instruction already completed description: Refund instruction already completed value: *ref_957 refundInstructionFailed: summary: Refund instruction failed description: Refund instruction failed value: *ref_958 signatureInstructionRequest: summary: Signature Instruction description: Submit an instruction for capturing a signature on a physical device. value: *ref_959 signatureInstructionInProgress: summary: Signature instruction description: Object that contains information about the progress of the signature instruction. value: *ref_960 signatureInstruction: summary: Signature instruction description: Object that contains information about the progress of the signature instruction. value: *ref_961 signatureInstructionCompleted: summary: Signature instruction already completed description: Signature instruction already completed value: *ref_962 signatureInstructionFailed: summary: Signature instruction failed description: Signature instruction failed value: *ref_963 signatureResponse: summary: Signature description: A signature response example. value: *ref_964 cardVerificationRequest: summary: Card Verification description: Card Verification value: *ref_965 cardVerificationResponse: summary: Card Verification description: Card Verification value: *ref_966 cardBalanceRequest: summary: Card Balance description: Card Balance value: *ref_967 cardBalanceResponse: summary: Card Balance description: Card Balance value: *ref_968 binLookupRequest: summary: BIN lookup description: BIN lookup value: *ref_969 binLookupResponse: summary: BIN lookup description: BIN lookup value: *ref_970 fxRateRequest: summary: Fx-Rate description: Fx-Rate value: *ref_971 fxRateResponse: summary: Fx-Rate description: Fx-Rate value: *ref_972 paginatedBankTransferPayment: summary: Bank Transfer Payment description: Bank Transfer Payment value: *ref_973 bankTransferPaymentRequestStoreTokenRequest: summary: Store Token Bank Transfer Payment description: Bank Transfer Payment with ACH payload and token storage value: *ref_974 bankTransferPaymentResponseStoreToken: summary: Store Token Bank Transfer Payment description: Bank Transfer Payment with ACH payload and token storage value: *ref_270 reverseBankTransferPayment: summary: Reverse Bank Transfer Payment description: Reverse Bank Transfer Payment value: *ref_975 refundBankTransferPaymentRequest: summary: Refund Bank Transfer Payment description: Refund Bank Transfer Payment value: *ref_976 refundBankTransferPaymentResponse: summary: Reverse Bank Transfer Payment description: Reverse Bank Transfer Payment value: *ref_977 representmentBankTransferPaymentRequest: summary: Representment Bank Transfer Payment description: Representment Bank Transfer Payment value: *ref_978 paginatedBankTransferUnreferencedRefundResponse: summary: Paginated Bank Transfer Unreferenced Refund description: Paginated Bank Transfer Unreferenced Refund value: *ref_979 bankTransferUnreferencedRefundRequest: summary: Bank Transfer Unreferenced Refund description: Bank Transfer Unreferenced Refund value: *ref_980 bankTransferUnreferencedRefundResponse: summary: Bank Transfer Unreferenced Refund description: Bank Transfer Unreferenced Refund value: *ref_283 reverseBankTransferUnreferencedRefundResponse: summary: Bank Transfer Unreferenced Refund description: Bank Transfer Unreferenced Refund value: *ref_981 bankAccountVerificationRequestPad: summary: PAD Bank Account Verification Request description: Bank Account Verification Request for PAD value: *ref_982 bankAccountVerificationRequestAch: summary: ACH Bank Account Verification Request description: Bank Account Verification Request for ACH value: *ref_983 bankAccountVerificationResponse: summary: Bank Account Verification Response description: Bank Account Verification Response value: *ref_984 listMerchantPlatforms: summary: Paginated list of merchant platforms description: Retrieve a list of merchant platforms associated with your account. value: *ref_985 createMerchantPlatform: summary: Create merchant platform description: Create a merchant platform. value: *ref_986 merchantPlatformCreated: summary: Created merchant platform description: New merchant platform created value: *ref_987 processingAccountFailed: summary: Failed processing account description: We successfully created the merchant platform, but failed to add one or more processing accounts. value: *ref_988 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_306 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_307 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_308 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_309 taxIdInUse: summary: Tax ID in use description: The tax ID supplied is already in use. value: *ref_989 nationalIdInUse: summary: National ID in use description: One or more supplied national IDs are not unique. All national IDs must be unique. value: *ref_990 retrievedMerchantPlatforms: summary: Retrieve merchant platform description: Retrieve a merchant platform. value: *ref_991 listProcessingAccounts: summary: Paginated list of processing account description: Retrieve processing accounts associated with a merchant platform. value: *ref_992 createProcessingAccount: summary: Create merchant platform description: Create a merchant platform. value: *ref_993 processingAccountCreated: summary: Retrieve merchant platform description: Retrieve a merchant platform. value: *ref_994 retrieveProcessingAccount: summary: Retrieve processing account description: Retrieve a specific processing account. value: *ref_995 listProcessingAccountFundingAccounts: summary: List of funding accounts description: List of funding accounts associated with a processing account. value: *ref_996 listContactsPaginated: summary: Paginated list of processing account contacts description: List of contacts associated with a processing account. value: *ref_997 retrieveProcessingAccountPricingAgreement: summary: Get processing account pricing agreement description: Retrieve a pricing agreement for a processing account. value: *ref_998 listProcessingAccountOwners: summary: Paginated list of processing account owners description: Retrieve owners associated with a processing account. value: *ref_999 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_1000 reminderCreated: summary: Reminder created description: Reminder created. value: *ref_1001 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_1002 contractAlreadySigned: summary: Contract already signed description: We couldn’t resend the email because the merchant already signed the contract. value: *ref_1003 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_1004 listTerminalOrders: summary: Paginated list of Terminal Orders description: Retrieve terminal orders associated with a processing account. value: *ref_1005 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_1006 terminalOrderCreated: summary: Terminal order description: Terminal order value: *ref_1007 listProcessingTemrinalsPaginated: summary: Paginated list of processing terminals description: List of processing terminals associated with a processing account. value: *ref_1008 retrieveProcessingTerminal: summary: Retrieve processing terminal description: Retrieve a specific processing terminal. value: *ref_1009 contact: summary: Contact object description: Contact object value: *ref_1010 updateContact: summary: Update contact description: Update a specific contact. value: *ref_1011 paginatedEventSubscriptions: summary: Paginated list of Event subscriptions description: Example of a paginated list of event subscriptions value: *ref_1012 createWebhookEventSubscription: summary: Create event subscription description: Create an event subscription value: *ref_1013 eventSubscriptionCreated: summary: Event subscription created description: Example of a created event subscription. value: *ref_1014 eventSubscription: summary: Event subscription description: Example of an event subscription. value: *ref_1015 updateEventSubscription: summary: Update event subscription description: Update an event subscription value: *ref_1016 patchEventSubscriptionRealistic: summary: Partially update event subscription description: | Partially update an existing event subscription. Structure your request to follow the RFC 6902 standard. value: *ref_1017 patchEventSubscription: summary: Patched event subscription description: Example of a patched event subscription. value: *ref_1018 terminalOrder: summary: Terminal order description: Terminal order value: *ref_1019 paginatedAchDeposits: summary: Paginated ACH deposits value: *ref_1020 achDepositIdError: summary: Bad Request description: One or more validation errors occurred value: *ref_1021 paginatedAchDepositFees: summary: Paginated ACH deposit fees value: *ref_1022 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_103 '413': description: Payload too large content: *ref_1023 '415': description: Unsupported media type content: *ref_104 '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_1024 x-tagGroups: - 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