openapi: 3.0.3 info: version: '1' title: Payroc API description: Api for accessing Payroc servicess contact: name: Payroc Helpdesk url: https://docs.payroc.com/api email: helpdesk@payroc.com servers: - url: https://api.payroc.com/v1/ description: External URL security: - bearerAuth: [] tags: - 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: 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: 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.](#getMerchantAcccounts) - [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](/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 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: 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: Subscriptions description: Subscribe customers to payment plans. paths: /funding-recipients: summary: Create and manage funding recipients. post: tags: - Funding recipients summary: Create funding recipient description: Create a funding recipient. 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 for the identifier. schema: &ref_21 type: string example: 8e03978e-40d5-43e8-bc93-6894a57f9324 requestBody: content: application/json: schema: required: &ref_246 - address - contactMethods - recipientType - taxId - owners - fundingAccounts - doingBuinessAs type: object title: create funding recipient properties: &ref_247 recipientId: type: integer readOnly: true example: 1 status: type: string readOnly: true example: approved enum: - approved - rejected - pending createdDate: type: string format: date-time example: '2020-09-08T12:00:00.000Z' readOnly: true lastModifiedDate: type: string format: date-time example: '2020-09-08T12:00:00.000Z' 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: Legal name that the business operates under. 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. example: 1 Example Ave. maxLength: 150 address2: type: string description: Address Line. example: Example Address Line 2 maxLength: 150 address3: type: string description: Address Line. example: Example Address Line 3 maxLength: 150 city: type: string description: City. example: Chicago maxLength: 50 state: type: string description: Name or postal abbreviation of the state. example: Illinois maxLength: 50 country: maxLength: 2 minLength: 2 type: string description: Two letter ISO 3166-1 country code. example: US postalCode: type: string description: Zip Code or Postcode. example: '60056' maxLength: 10 contactMethods: type: array minItems: 1 xml: wrapped: true 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: oneOf: &ref_2 - required: &ref_232 - type - value type: object title: Email contact method properties: &ref_233 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_234 - type - value type: object title: Phone number contact method properties: &ref_235 type: type: string description: Type of contact method. enum: - phone value: type: string description: Phone Number. maxLength: 15 example: '2025550164' - required: &ref_236 - type - value type: object title: Mobile number contact method properties: &ref_237 type: type: string description: Type of contact method. enum: - mobile value: type: string description: Mobile Number. maxLength: 15 example: '8447297624' - required: &ref_238 - type - value type: object title: Fax number contact method properties: &ref_239 type: type: string description: Type of contact method. enum: - fax value: type: string description: Fax Number. maxLength: 15 example: '2025550110' example: - type: email value: david.smith@example.com metadata: type: object additionalProperties: type: string description: '[Metadata](/api/metadata) object you can use to include custom data with your request.' example: customerId: '2345' owners: minItems: 1 description: Array of owner objects that you can use to add owners to the funding recipient. type: array xml: wrapped: true items: xml: name: owners type: object title: owner required: &ref_27 - firstName - lastName - dateOfBirth - identifiers - contactMethods - relationship - address properties: &ref_28 ownerId: type: integer description: Unique identifier of 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 xml: wrapped: true description: Array of identifier objects. example: - type: nationalId value: xxxxx4320 items: required: &ref_186 - type - value type: object title: identifier properties: &ref_187 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: oneOf: *ref_2 relationship: description: Object that contains information about the owner's relationship to the business. allOf: - required: &ref_241 - isControlProng type: object title: Owner relationship description: Object that contains information about the owner's relationship to the business. properties: &ref_242 equityPercentage: type: number description: Percentage of the business that the owner holds. format: percentage example: 35.4 default: 0 title: type: string description: Owner's job title within the business. example: CFO isControlProng: type: boolean description: Indicates if the owner is a control prong within the business. Only one control prong should be identified. example: true isAuthorizedSignatory: type: boolean description: Indicates if the owner is an authorized signatory within the business. example: false fundingAccounts: minItems: 1 description: Array of fundingAccount objects that you can use to add funding accounts to the funding recipient. type: array xml: wrapped: true items: xml: name: fundingAccount required: &ref_19 - nameOnAccount - paymentMethods - type - use type: object title: funding account properties: &ref_20 fundingAccountId: type: integer description: Unique identifier of the funding account. readOnly: true example: 123 createdDate: type: string description: Date the funding account was created. format: date-time example: '2020-09-08T12:00:00.000Z' readOnly: true lastModifiedDate: type: string description: Date the funding account was last modified. format: date-time example: '2020-09-08T12:00:00.000Z' readOnly: true status: type: string description: Status of the funding account. readOnly: true example: pending enum: - approved - rejected - pending - hold type: type: string description: Type of funding account. enum: - checking - savings - generalLedger 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. 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 xml: &ref_244 wrapped: true items: &ref_245 title: payment method xml: name: paymentMethod oneOf: - type: object title: ACH payment method properties: &ref_243 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' metadata: type: object additionalProperties: type: string description: '[Metadata](/api/metadata) object you can use to include custom data with your request.' example: internalRef: '2345' links: readOnly: true type: array description: Array of HATEOAS links. items: type: object description: Object that contains information about a HATEOAS link. If we can't match a dispute to a transaction, we don't return a 'link' object. properties: &ref_3 rel: type: string method: type: string href: type: string required: &ref_4 - href - method - rel example: &ref_5 rel: previous method: get href: responses: '201': description: Successful request. We created the funding recipient. content: application/json: schema: required: &ref_6 - address - contactMethods - recipientType - taxId - owners - fundingAccounts - doingBuinessAs type: object title: funding recipient properties: &ref_7 recipientId: type: integer description: Unique identifier of the funding recipient. readOnly: true example: 1 status: type: string description: Indicates if we have approved the funding recipient. readOnly: true example: approved enum: - approved - rejected - pending createdDate: type: string description: Date the funding recipient was created. format: date-time example: '2020-09-08T12:00:00.000Z' readOnly: true lastModifiedDate: type: string description: Date the funding recipient was last modified. format: date-time example: '2020-09-08T12:00:00.000Z' readOnly: true recipientType: type: string example: privateCorporation enum: - privateCorporation - publicCorporation - nonProfit - government - privateLlc - publicLlc - privatePartnership - publicPartnership - soleProprietor 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. doingBuinessAs: type: string description: Legal name that the business operates under. 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 xml: wrapped: true description: Array of contactMethod objects for the funding recipient. items: oneOf: *ref_2 example: - type: email value: david.smith@example.com metadata: type: object additionalProperties: type: string description: '[Metadata](/api/metadata) object you can use to include custom data with your request.' example: customerId: '2345' owners: readOnly: true description: Array of owner objects associated with the funding recipient. type: array xml: wrapped: true items: type: object title: owner summary xml: name: owner properties: ownerId: type: integer description: Unique identifier of the owner. example: 4564 link: type: object description: Array of HATEOAS links for viewing the owner. properties: rel: type: string example: owner href: type: string example: https://api.payroc.com/v1/owners/4564 method: type: string example: get fundingAccounts: readOnly: true description: Array of fundingAccount objects associated with the funding recipient. type: array xml: wrapped: true items: type: object title: funding account summary xml: name: funding account properties: fundingAccountId: type: integer description: Unique identifier of the funding account. example: 2 status: type: string example: pending description: Status of the funding account. enum: - approved - rejected - pending - hold link: type: object description: HATEOAS links for viewing the funding account. properties: rel: type: string example: fundingAccount href: type: string example: https://api.payroc.com/v1/funding-accounts/2 method: type: string example: get example: - fundingAccountId: 1 status: approved link: rel: fundingAccount href: https://api.payroc.com/v1/funding-accounts/1 method: get - fundingAccountId: 2 status: rejected link: rel: fundingAccount href: https://api.payroc.com/v1/funding-accounts/2 method: get headers: location: description: URI reference to created resource. style: simple explode: false schema: &ref_22 type: string '400': description: Validation errors content: application/problem+json: schema: type: object properties: &ref_8 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 fundingAccountId: type: integer description: Identifier for funding account. example: 1234 required: &ref_9 - type - title - detail - status examples: idempotentKeyMissing: summary: Idempotency key missing description: Idempotency key must be supplied value: &ref_23 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_10 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_16 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_11 application/problem+json: schema: type: object properties: &ref_220 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_221 - type - title - status - detail examples: notAuthorized: summary: Not Authorized description: Your identity could not be verified value: &ref_442 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_12 application/problem+json: schema: type: object properties: &ref_222 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/webhook/3 resource: type: string description: Resource the action was attempted on example: webhook required: &ref_223 - type - title - status - detail examples: forbidden: summary: Forbidden description: You do not have the required permission value: &ref_443 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/webhook/3 resource: webhook '406': description: Not acceptable content: &ref_18 application/problem+json: schema: type: object properties: &ref_226 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_227 - type - title - status - detail examples: notAcceptable: summary: Not acceptable description: Requested representation not supported value: &ref_445 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_24 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/webhook/3 required: &ref_25 - type - title - status - detail examples: idempotentKeyInUse: summary: Idempotency key in use description: Idempotency key in use value: &ref_26 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_13 application/problem+json: schema: type: object properties: &ref_230 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_231 - type - title - status - detail examples: apiError: summary: Api error description: Unable to process your request. value: &ref_444 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: Retrieve a list of all funding recipients associated with the ISV. operationId: listFundingRecipients parameters: - name: before in: query required: false description: Points to the resource identifier that you want to receive your results before. Typically, this is the first resource on the previous page. explode: false schema: &ref_29 type: string example: '2571' - name: after in: query description: Points to the resource identifier that you want to receive your results after. Typically, this is the last resource on the previous page. schema: &ref_30 type: string example: '8516' - name: limit in: query description: States the total amount of results the response is limited to. schema: &ref_31 type: integer default: 10 maximum: 100 example: 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_240 - type: object description: Contains the pagination properties that you use to navigate through a list of results. properties: &ref_32 limit: type: number description: Maximum number of results that we return for each page. example: 25 count: type: number description: Number of results that we returned. example: 23 hasMore: type: boolean description: Indicates that further results are 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 description: Object that contains information about a HATEOAS link. If we can't match a dispute to a transaction, we don't return a 'link' object. properties: *ref_3 required: *ref_4 example: *ref_5 - type: object properties: data: type: array description: An array of funding recipients items: required: *ref_6 type: object title: funding recipient properties: *ref_7 examples: paginatedFundingRecipients: summary: Paginated funding recipients. description: Paginated list of funding recipients. value: &ref_441 limit: 10 count: 1 hasMore: false links: - rel: previous method: get href: https://api.payroc.com/v1/funding-recipients?before=12345&limit=10 data: - recipientId: 12345 status: approved createdDate: '2020-09-08T12:00:00.000Z' lastModifiedDate: '2020-09-08T12:00:00.000Z' recipientType: privateCorporation taxId: '123456789' doingBuinessAs: Example llc address: address1: 1 Example Ave. city: Chicago state: Illinois country: US postalCode: '60056' contactMethods: - type: phone value: 123 456 7890 metadata: customerId: '12345' owners: - ownerId: 4564 link: rel: owner method: get href: https://api.payroc.com/v1/owners/4564 fundingAccounts: - fundingAccountId: 1 status: approved link: rel: fundingAccount method: get href: https://api.payroc.com/v1/funding-accounts/1 - fundingAccountId: 2 status: hold link: rel: fundingAccount method: get href: https://api.payroc.com/v1/funding-accounts/2 noActivity: summary: No records found description: Valid request, but no records match the criteria. value: &ref_47 limit: 10 count: 0 hasMore: false links: [] data: [] '400': description: Invalid request content: &ref_14 application/problem+json: schema: type: object properties: *ref_8 required: *ref_9 examples: badRequest: summary: Bad Request description: One or more validation errors occurred value: *ref_10 '401': description: Identity could not be verified content: *ref_11 '403': description: Do not have permissions to perform this action content: *ref_12 '500': description: An error has occured content: *ref_13 /funding-recipients/{recipientId}: get: tags: - Funding recipients summary: Retrieve a funding recipient description: Retrieve a specific funding recipient. operationId: getFundingRecipient parameters: - name: recipientId description: Unique identifier of the funding recipient. in: path required: true style: simple explode: false schema: &ref_15 type: integer responses: '200': description: Successful request. Returns the requested funding recipient. content: application/json: schema: required: *ref_6 type: object title: funding recipient properties: *ref_7 examples: fundingRecipient: summary: Funding recipient. description: Funding recipients. value: &ref_446 recipientId: 12345 status: approved createdDate: '2020-09-08T12:00:00.000Z' lastModifiedDate: '2020-09-08T12:00:00.000Z' recipientType: privateCorporation taxId: '123456789' doingBuinessAs: Example llc address: address1: 1 Example Ave. city: Chicago state: Illinois country: US postalCode: '60056' contactMethods: - type: phone value: 123 456 7890 metadata: customerId: '12345' owners: - ownerId: 4564 link: rel: owner method: get href: https://api.payroc.com/v1/owners/4564 fundingAccounts: - fundingAccountId: 1 status: approved link: rel: fundingAccount method: get href: https://api.payroc.com/v1/funding-accounts/1 - fundingAccountId: 2 status: hold link: rel: fundingAccount method: get href: https://api.payroc.com/v1/funding-accounts/2 '400': description: Invalid request content: *ref_14 '401': description: Identity could not be verified content: *ref_11 '403': description: Do not have permissions to perform this action content: *ref_12 '404': description: Resource not found content: &ref_17 application/problem+json: schema: type: object properties: &ref_224 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 account was not found resource: type: string description: Resource that was not found example: Account required: &ref_225 - type - title - status - detail examples: notFound: summary: Not found description: Resource could not be found value: &ref_447 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_13 put: tags: - Funding recipients summary: Update funding recipient description: Update a funding recipient. If you make significant changes, we may need to approve the funding recipient again. operationId: updateFundingRecipient parameters: - name: recipientId description: Unique identifier of the funding recipient. in: path required: true style: simple explode: false schema: *ref_15 requestBody: content: application/json: schema: required: *ref_6 type: object title: funding recipient properties: *ref_7 responses: '204': description: Successful request. We updated the funding recipient. '400': description: Validation errors content: application/problem+json: schema: type: object properties: *ref_8 required: *ref_9 examples: validationError: summary: Bad Request description: One or more validation errors occurred value: *ref_10 kycCheckFailed: summary: KYC check failed description: KYC check failed value: *ref_16 '401': description: Identity could not be verified content: *ref_11 '403': description: Do not have permissions to perform this action content: *ref_12 '404': description: Resource not found content: *ref_17 '406': description: Not acceptable content: *ref_18 '500': description: An error has occured content: *ref_13 delete: tags: - Funding recipients summary: Delete funding recipient description: Delete a funding recipient. This includes funding accounts and owners linked to the funding recipient. operationId: deleteFundingRecipient parameters: - name: recipientId description: Unique identifier of the funding recipient. in: path required: true style: simple explode: false schema: *ref_15 responses: '204': description: Successful request. We deleted the funding recipient. '400': description: Invalid request content: *ref_14 '401': description: Identity could not be verified content: *ref_11 '403': description: Do not have permissions to perform this action content: *ref_12 '404': description: Resource not found content: *ref_17 '500': description: An error has occured content: *ref_13 /funding-recipients/{recipientId}/funding-accounts: get: tags: - Funding recipients summary: List funding accounts description: Retrieve all funding accounts associated with the funding recipient. operationId: listFundRecipientFundingAccounts parameters: - name: recipientId description: Unique identifier of the funding recipient. in: path required: true style: simple explode: false schema: *ref_15 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_19 type: object title: funding account properties: *ref_20 examples: fundingAccounts: summary: List of funding accounts description: List of funding accounts. value: &ref_448 - fundingAccountId: 123 createdDate: '2020-09-08T12:00:00.000Z' lastModifiedDate: '2020-09-08T12:00:00.000Z' status: approved type: checking use: credit nameOnAccount: Jane Doe paymentMethods: - type: ach value: routingNumber: '*****6789' accountNumber: '******7890' metadata: internalRef: '2345' links: - rel: parent href: https://api.payroc.com/v1/funding-recipient/2 method: get - fundingAccountId: 124 createdDate: '2021-01-08T12:00:00.000Z' lastModifiedDate: '2021-01-08T12:00:00.000Z' status: pending type: checking use: debit nameOnAccount: Jane Doe paymentMethods: - type: ach value: routingNumber: '*****8725' accountNumber: '******3491' metadata: internalRef: '2346' links: - rel: parent href: https://api.payroc.com/v1/funding-recipient/2 method: get '400': description: Invalid request content: *ref_14 '401': description: Identity could not be verified content: *ref_11 '403': description: Do not have permissions to perform this action content: *ref_12 '404': description: Resource not found content: *ref_17 '500': description: An error has occured content: *ref_13 post: tags: - Funding recipients summary: Create funding account description: Create a new funding account, and add it to the funding recipient. operationId: createFundRecipientFundingAccount parameters: - name: recipientId description: Unique identifier of the funding recipient. in: path required: true style: simple explode: false schema: *ref_15 - name: Idempotency-Key in: header required: true description: Unique identifier that you generate for each request. You must use the UUID v4 format for the identifier. schema: *ref_21 example: 8e03978e-40d5-43e8-bc93-6894a57f9324 requestBody: content: application/json: schema: required: *ref_19 type: object title: funding account properties: *ref_20 responses: '201': description: Successful request. We created the funding account and added it to the funding recipient. content: application/json: schema: required: *ref_19 type: object title: funding account properties: *ref_20 examples: fundingAccount: summary: Funding account description: Funding accounts. value: &ref_449 fundingAccountId: 123 createdDate: '2020-09-08T12:00:00.000Z' lastModifiedDate: '2020-09-08T12:00:00.000Z' status: approved type: checking use: credit nameOnAccount: Jane Doe paymentMethods: - type: ach value: routingNumber: '*****6789' accountNumber: '******7890' metadata: internalRef: '2345' links: - rel: parent href: https://api.payroc.com/v1/funding-recipient/2 method: get headers: location: description: URI reference to created resource. style: simple explode: false schema: *ref_22 '400': description: Validation errors content: application/problem+json: schema: type: object properties: *ref_8 required: *ref_9 examples: idempotentKeyMissing: summary: Idempotency key missing description: Idempotency key must be supplied value: *ref_23 validationError: summary: Bad Request description: One or more validation errors occurred value: *ref_10 kycCheckFailed: summary: KYC check failed description: KYC check failed value: *ref_16 '401': description: Identity could not be verified content: *ref_11 '403': description: Do not have permissions to perform this action content: *ref_12 '404': description: Resource not found content: *ref_17 '406': description: Not acceptable content: *ref_18 '409': description: Conflict content: application/problem+json: schema: type: object properties: *ref_24 required: *ref_25 examples: idempotentKeyInUse: summary: Idempotency key in use description: Idempotency key in use value: *ref_26 '500': description: An error has occured content: *ref_13 /funding-recipients/{recipientId}/owners: get: tags: - Funding recipients summary: List funding recipient owners description: Retrieve all owners associated with the funding recipient. operationId: listFundRecipientOwners parameters: - name: recipientId description: Unique identifier of the funding recipient. in: path required: true style: simple explode: false schema: *ref_15 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_27 properties: *ref_28 '400': description: Invalid request content: *ref_14 '401': description: Identity could not be verified content: *ref_11 '403': description: Do not have permissions to perform this action content: *ref_12 '404': description: Resource not found content: *ref_17 '500': description: An error has occured content: *ref_13 post: tags: - Funding recipients summary: Create funding recipient owner description: Create a new owner, and add it to the funding recipient. operationId: createFundRecipientOwner parameters: - name: recipientId description: Unique identifier of the funding recipient. in: path required: true style: simple explode: false schema: *ref_15 - name: Idempotency-Key in: header required: true description: Unique identifier that you generate for each request. You must use the UUID v4 format for the identifier. schema: *ref_21 example: 8e03978e-40d5-43e8-bc93-6894a57f9324 requestBody: content: application/json: schema: type: object title: owner required: *ref_27 properties: *ref_28 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_27 properties: *ref_28 headers: location: description: URI reference to created resource. style: simple explode: false schema: *ref_22 '400': description: Validation errors content: application/problem+json: schema: type: object properties: *ref_8 required: *ref_9 examples: idempotentKeyMissing: summary: Idempotency key missing description: Idempotency key must be supplied value: *ref_23 validationError: summary: Bad Request description: One or more validation errors occurred value: *ref_10 kycCheckFailed: summary: KYC check failed description: KYC check failed value: *ref_16 '401': description: Identity could not be verified content: *ref_11 '403': description: Do not have permissions to perform this action content: *ref_12 '404': description: Resource not found content: *ref_17 '406': description: Not acceptable content: *ref_18 '409': description: Conflict content: application/problem+json: schema: type: object properties: *ref_24 required: *ref_25 examples: idempotentKeyInUse: summary: Idempotency key in use description: Idempotency key in use value: *ref_26 '500': description: An error has occured content: *ref_13 /funding-accounts: get: tags: - Funding accounts summary: List funding accounts description: Retrieve a list of all funding accounts associated with the ISV. operationId: listFundingAccount parameters: - name: before in: query required: false description: Points to the resource identifier that you want to receive your results before. Typically, this is the first resource on the previous page. explode: false schema: *ref_29 example: '2571' - name: after in: query description: Points to the resource identifier that you want to receive your results after. Typically, this is the last resource on the previous page. schema: *ref_30 example: '8516' - name: limit in: query description: States the total amount of results the response is limited to. schema: *ref_31 example: 25 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_248 - type: object description: Contains the pagination properties that you use to navigate through a list of results. properties: *ref_32 - type: object properties: data: type: array description: Array of fundingAccount objects. items: required: *ref_19 type: object title: funding account properties: *ref_20 required: - data examples: fundingAccountExample: summary: Paginated funding accounts value: &ref_450 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: '2020-09-08T12:00:00.000Z' lastModifiedDate: '2020-09-08T12:00:00.000Z' status: approved type: checking use: credit nameOnAccount: Jane Doe paymentMethods: - type: ach value: routingNumber: '*****6789' accountNumber: '******7890' metadata: internalRef: '2345' links: - rel: parent href: https://api.payroc.com/v1/merchants/1234 method: get - fundingAccountId: 124 createdDate: '2021-01-08T12:00:00.000Z' lastModifiedDate: '2021-01-08T12:00:00.000Z' status: pending type: checking use: debit nameOnAccount: Jane Doe paymentMethods: - type: ach value: routingNumber: '*****8725' accountNumber: '******3491' metadata: internalRef: '2346' links: - rel: parent href: https://api.payroc.com/v1/funding-recipient/2 method: get noResults: summary: No results found description: No results found value: &ref_451 limit: 10 count: 0 hasMore: false links: [] data: [] '400': description: Invalid request content: *ref_14 '401': description: Identity could not be verified content: *ref_11 '403': description: Do not have permissions to perform this action content: *ref_12 '404': description: Resource not found content: *ref_17 '500': description: An error has occured content: *ref_13 /funding-accounts/{fundingAccountId}: get: tags: - Funding accounts summary: Retrieve funding account description: Retrieve a specific funding account. operationId: getFundingAccount parameters: - name: fundingAccountId in: path required: true description: Unique identifier of the funding account. style: simple explode: false schema: &ref_33 type: integer responses: '200': description: Successful request. Returns the requested funding account. content: application/json: schema: required: *ref_19 type: object title: funding account properties: *ref_20 examples: fundingAccountExample: summary: Masked funding account example. value: &ref_452 fundingAccountId: 123 createdDate: '2020-09-08T12:00:00.000Z' lastModifiedDate: '2020-09-08T12:00:00.000Z' status: pending type: checking use: credit nameOnAccount: Jane Doe paymentMethods: - type: ach value: routingNumber: '*****6789' accountNumber: '******7890' metadata: internalRef: '2345' links: - rel: parent href: https://api.payroc.com/v1/merchants/1234 method: get '400': description: Invalid request content: *ref_14 '401': description: Identity could not be verified content: *ref_11 '403': description: Do not have permissions to perform this action content: *ref_12 '404': description: Resource not found content: *ref_17 '500': description: An error has occured content: *ref_13 put: tags: - Funding accounts summary: Update funding account description: Update a funding account. operationId: updateFundingAccount parameters: - name: fundingAccountId in: path required: true description: Unique identifier of the funding account. style: simple explode: false schema: *ref_33 requestBody: content: application/json: schema: required: *ref_19 type: object title: funding account properties: *ref_20 responses: '204': description: Successful request. We updated the funding account. '400': description: Validation errors content: application/problem+json: schema: type: object properties: *ref_8 required: *ref_9 examples: validationError: summary: Bad Request description: One or more validation errors occurred value: *ref_10 kycCheckFailed: summary: KYC check failed description: KYC check failed value: *ref_16 '401': description: Identity could not be verified content: *ref_11 '403': description: Do not have permissions to perform this action content: *ref_12 '404': description: Resource not found content: *ref_17 '406': description: Not acceptable content: *ref_18 '500': description: An error has occured content: *ref_13 delete: tags: - Funding accounts summary: Delete funding account description: Delete a funding account. operationId: deleteFundingAccount parameters: - name: fundingAccountId in: path required: true description: Unique identifier of the funding account. style: simple explode: false schema: *ref_33 responses: '204': description: Successful request. We deleted the funding account. '400': description: Invalid request content: *ref_14 '401': description: Identity could not be verified content: *ref_11 '403': description: Do not have permissions to perform this action content: *ref_12 '404': description: Resource not found content: *ref_17 '500': description: An error has occured content: *ref_13 /owners/{ownerId}: get: tags: - Owners summary: Retrieve owner description: Retrieve a specific owner. operationId: getOwner parameters: - name: ownerId in: path description: Unique identifier for the owner. required: true style: simple explode: false schema: &ref_34 type: integer example: 4564 responses: '200': description: Successful request. Returns the requested owner. content: application/json: schema: type: object title: owner required: *ref_27 properties: *ref_28 examples: retrievedOwner: summary: Retrieve owner description: Retrieve a specific owner. value: &ref_453 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: 35.4 title: CFO isControlProng: true isAuthorizedSignatory: false '400': description: Invalid request content: *ref_14 '401': description: Identity could not be verified content: *ref_11 '403': description: Do not have permissions to perform this action content: *ref_12 '404': description: Resource not found content: *ref_17 '500': description: An error has occured content: *ref_13 put: tags: - Owners summary: Update owner description: Update a specific owner. operationId: updateOwner parameters: - name: ownerId in: path description: Unique identifier for the owner. required: true style: simple explode: false schema: *ref_34 example: 4564 requestBody: content: application/json: schema: type: object title: owner required: *ref_27 properties: *ref_28 examples: updateOwner: summary: Update owner description: Update a specific owner. value: &ref_454 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: 35.4 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_8 required: *ref_9 examples: validationError: summary: Bad Request description: One or more validation errors occurred value: *ref_10 kycCheckFailed: summary: KYC check failed description: KYC check failed value: *ref_16 '401': description: Identity could not be verified content: *ref_11 '403': description: Do not have permissions to perform this action content: *ref_12 '404': description: Resource not found content: *ref_17 '406': description: Not acceptable content: *ref_18 '500': description: An error has occured content: *ref_13 delete: tags: - Owners summary: Delete owner description: Delete a owner. operationId: deleteOwner parameters: - name: ownerId in: path description: Unique identifier for the owner. required: true style: simple explode: false schema: *ref_34 example: 4564 responses: '204': description: Successful request. We deleted the owner. '400': description: Invalid request content: *ref_14 '401': description: Identity could not be verified content: *ref_11 '403': description: Do not have permissions to perform this action content: *ref_12 '404': description: Resource not found content: *ref_17 '500': description: An error has occured content: *ref_13 /pricing-intents: summary: Provides capabilities to list and create pricing intents. get: summary: List pricing intents description: Retrieve a list of pricing intents. operationId: listPricingIntents tags: - Pricing intents parameters: - name: before in: query required: false description: Points to the resource identifier that you want to receive your results before. Typically, this is the first resource on the previous page. explode: false schema: *ref_29 example: '2571' - name: after in: query description: Points to the resource identifier that you want to receive your results after. Typically, this is the last resource on the previous page. schema: *ref_30 example: '8516' - name: limit in: query description: States the total amount of results the response is limited to. schema: *ref_31 example: 25 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_277 - type: object description: Contains the pagination properties that you use to navigate through a list of results. properties: *ref_32 - 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_48 - type: object title: pricing intent version 4.0 description: Object that contains information about a pricing intent for Merchant Processing Agreement (MPA) 4.0. allOf: &ref_276 - type: object title: base pricing intent description: Object that contains information about the base fees. properties: &ref_249 id: type: string description: Unique identifier of the pricing intent. readOnly: true createdDate: type: string example: '2020-09-22T09:00:00' format: date-time description: Creation date of the pricing intent. readOnly: true lastUpdatedDate: type: string example: '2020-09-22T09:00:00' format: date-time description: Date of the most recent change to the pricing intent. readOnly: true status: type: string description: Status of the pricing intent. readOnly: true enum: - active - pendingReview - rejected key: type: string description: Unique identifier that you use to connect a merchant to the pricing intent. metadata: type: object additionalProperties: type: string description: '[Metadata](/api/metadata) object that contains your custom data.' example: internalReference: '2345' required: &ref_250 - key - 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_184 - country - version - base properties: &ref_185 country: type: string description: Indicates the country that the pricing intent applies to. enum: - US version: type: string description: Version of the MPA. default: '4.0' enum: - '4.0' base: type: object title: US base fees description: Object that contains information about U.S. base fees. properties: &ref_251 addressVerification: description: Fee for each address verification request. The value is in the currency's lowest denomination, for example, cents. type: integer example: 5 minimum: 0 nullable: true annualFee: type: object description: Object that contains information about the annual fee. properties: billInMonth: type: string description: Indicates the month in which we collect the annual fee. default: december enum: - june - december 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 description: Annual fee for the regulatory assistance program. The value is in the currency's lowest denomination, for example, cents. minimum: 0 example: 15 nullable: true pciNonCompliance: type: integer description: Monthly fee for PCI noncompliance. The value is in the currency's lowest denomination, for example, cents. minimum: 0 example: 4995 default: 4995 merchantAdvantage: type: integer description: Monthly fee for Payroc Advantage. The value is in the currency's lowest denomination, for example, cents. minimum: 0 example: 10 nullable: true platinumSecurity: description: Object that contains information about the Platinum Security fee. type: object oneOf: - type: object title: Monthly platinum security required: - billingFrequency properties: 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: - billingFrequency properties: 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: 0 example: 500 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: 0 example: 95 default: 95 chargeback: type: integer description: Fee for each chargeback. The value is in the currency's lowest denomination, for example, cents. minimum: 0 example: 2500 default: 2500 retrieval: type: integer description: Fee for each retrieval. The value is in the currency's lowest denomination, for example, cents. minimum: 0 example: 1500 default: 1500 batch: type: integer description: Fee for each batch. The value is in the currency's lowest denomination, for example, cents. minimum: 0 example: 1500 earlyTermination: type: integer description: Fee for early termination. The value is in the currency's lowest denomination, for example, cents. minimum: 0 example: 57500 default: 57500 required: &ref_252 - 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: &ref_273 card: type: object description: Object that contains information about card fees. oneOf: - type: object title: Interchange Plus Plan description: Object that contains information about Interchange Plus. properties: &ref_253 planType: type: string description: Type of processing plan. enum: - interchangePlus fees: description: Object that contains information about the fees. type: object properties: mastercardVisaDiscover: type: object title: Processor Fee description: Object that contains information about the processor fees. properties: &ref_35 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: oneOf: - type: object title: American Express OptBlue required: - type - volume - transaction properties: type: type: string 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: - type - transaction properties: type: type: string 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 required: &ref_36 - additionalDiscount - transaction - monthlyAccess properties: &ref_37 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 required: &ref_38 - transaction properties: &ref_39 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 required: &ref_40 - enrollment - creditToMerchant properties: &ref_41 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 required: &ref_42 - transaction properties: &ref_43 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_254 - planType - fees - type: object title: Interchange Plus with three tiers description: Object that contains information about Interchange Plus with three tiers. properties: &ref_255 planType: type: string description: Type of processing plan. enum: - interchangePlusTiered3 fees: type: object description: Object that contains information about the fees. properties: mastercardVisaDiscover: type: object required: &ref_44 - qualifiedRate - midQualRate - nonQualRate properties: &ref_45 qualifiedRate: type: object title: Processor Fee description: Object that contains information about the processor fees. properties: *ref_35 midQualRate: type: object title: Processor Fee description: Object that contains information about the processor fees. properties: *ref_35 nonQualRate: type: object title: Processor Fee description: Object that contains information about the processor fees. properties: *ref_35 amex: oneOf: - type: object title: American Express OptBlue required: - type - qualifiedRate - midQualRate - nonQualRate properties: type: type: string enum: - optBlue qualifiedRate: type: object title: Processor Fee description: Object that contains information about the processor fees. properties: *ref_35 midQualRate: type: object title: Processor Fee description: Object that contains information about the processor fees. properties: *ref_35 nonQualRate: type: object title: Processor Fee description: Object that contains information about the processor fees. properties: *ref_35 - type: object title: American Express Direct required: - type - transaction properties: type: type: string 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 required: *ref_36 properties: *ref_37 electronicBenefitsTransfer: type: object required: *ref_38 properties: *ref_39 enhancedInterchange: type: object required: *ref_40 properties: *ref_41 specialityCards: type: object required: *ref_42 properties: *ref_43 required: - mastercardVisaDiscover required: &ref_256 - planType - fees - type: object title: Tiered pricing with three tiers description: Object that contains information about tiered pricing with three tiers. properties: &ref_257 planType: type: string description: Type of processing plan. enum: - tiered3 fees: type: object description: Object that contains information about the fees. properties: mastercardVisaDiscover: type: object required: *ref_44 properties: *ref_45 amex: oneOf: - type: object title: American Express OptBlue required: - type - qualifiedRate - midQualRate - nonQualRate properties: type: type: string enum: - optBlue qualifiedRate: type: object title: Processor Fee description: Object that contains information about the processor fees. properties: *ref_35 midQualRate: type: object title: Processor Fee description: Object that contains information about the processor fees. properties: *ref_35 nonQualRate: type: object title: Processor Fee description: Object that contains information about the processor fees. properties: *ref_35 - type: object title: American Express Direct required: - type - transaction properties: type: type: string 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 required: *ref_36 properties: *ref_37 electronicBenefitsTransfer: type: object required: *ref_38 properties: *ref_39 specialityCards: type: object required: *ref_42 properties: *ref_43 required: - mastercardVisaDiscover required: &ref_258 - planType - fees - type: object title: Tiered pricing with four tiers description: Object that contains information about tiered pricing with four tiers. properties: &ref_259 planType: type: string description: Type of processing plan. enum: - tiered4 fees: type: object description: Object that contains information about the fees. properties: mastercardVisaDiscover: type: object allOf: &ref_46 - type: object required: *ref_44 properties: *ref_45 - type: object required: - premiumRate properties: premiumRate: type: object title: Processor Fee description: Object that contains information about the processor fees. properties: *ref_35 amex: oneOf: - type: object title: American Express OptBlue required: - type - qualifiedRate - midQualRate - nonQualRate properties: type: type: string enum: - optBlue qualifiedRate: type: object title: Processor Fee description: Object that contains information about the processor fees. properties: *ref_35 midQualRate: type: object title: Processor Fee description: Object that contains information about the processor fees. properties: *ref_35 nonQualRate: type: object title: Processor Fee description: Object that contains information about the processor fees. properties: *ref_35 - type: object title: American Express Direct required: - type - transaction properties: type: type: string 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 required: *ref_36 properties: *ref_37 electronicBenefitsTransfer: type: object required: *ref_38 properties: *ref_39 specialityCards: type: object required: *ref_42 properties: *ref_43 required: - mastercardVisaDiscover required: &ref_260 - planType - fees - type: object title: Tiered pricing with six tiers description: Object that contains information about tiered pricing with six tiers. properties: &ref_262 planType: type: string description: Type of processing plan. enum: - tiered6 fees: type: object description: Object that contains information about the fees. properties: mastercardVisaDiscover: type: object allOf: &ref_261 - type: object allOf: *ref_46 - type: object required: - regulatedCheckCard - unregulatedCheckCard properties: regulatedCheckCard: type: object title: Processor Fee description: Object that contains information about the processor fees. properties: *ref_35 unregulatedCheckCard: type: object title: Processor Fee description: Object that contains information about the processor fees. properties: *ref_35 amex: oneOf: - type: object title: American Express OptBlue required: - type - qualifiedRate - midQualRate - nonQualRate properties: type: type: string enum: - optBlue qualifiedRate: type: object title: Processor Fee description: Object that contains information about the processor fees. properties: *ref_35 midQualRate: type: object title: Processor Fee description: Object that contains information about the processor fees. properties: *ref_35 nonQualRate: type: object title: Processor Fee description: Object that contains information about the processor fees. properties: *ref_35 - type: object title: American Express Direct required: - type - transaction properties: type: type: string 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 required: *ref_36 properties: *ref_37 electronicBenefitsTransfer: type: object required: *ref_38 properties: *ref_39 specialityCards: type: object required: *ref_42 properties: *ref_43 required: - mastercardVisaDiscover required: &ref_263 - planType - fees - type: object title: Flat Rate Plan description: Object that contains information about Flat Rate. properties: &ref_264 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: type: object title: Processor Fee description: Object that contains information about the processor fees. properties: *ref_35 amex: oneOf: - type: object title: American Express Direct required: - type - transaction properties: type: type: string 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 required: *ref_36 properties: *ref_37 electronicBenefitsTransfer: type: object required: *ref_38 properties: *ref_39 specialityCards: type: object required: *ref_42 properties: *ref_43 required: - standardCards required: &ref_265 - planType - fees - type: object title: Consumer Choice Plan description: Object that contains information about ConsumerChoice. properties: &ref_266 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. 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 required: *ref_36 properties: *ref_37 electronicBenefitsTransfer: type: object required: *ref_38 properties: *ref_39 specialityCards: type: object required: *ref_42 properties: *ref_43 required: - monthlySubscription - volume required: &ref_267 - planType - fees - type: object title: RewardPay Plan description: Object that contains information about RewardPay. properties: &ref_268 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. 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 - prompt - tipAdjust specialityCards: type: object required: *ref_42 properties: *ref_43 required: - monthlySubscription - tips required: &ref_269 - planType - fees - type: object title: RewardPayChoice Plan description: Object that contains information about RewardPayChoice. properties: &ref_270 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. 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: 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 - prompt - 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 required: *ref_42 properties: *ref_43 required: - monthlySubscription - debit - credit required: &ref_271 - planType - fees ach: type: object properties: &ref_272 fees: 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. title: gateway fees properties: &ref_274 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_275 - fees examples: paginatedResults: summary: Paginated pricing intent description: Example of a paginated pricing intent. value: &ref_455 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: '2020-09-22T09:00:00' lastUpdatedDate: '2020-09-22T09:00:00' status: pendingReview key: base country: US version: '4.0' base: addressVerification: 5 annualFee: billInMonth: december 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 additionalServiceMonthly: 0 noActivity: summary: No records found description: Valid request, but no records match the criteria. value: *ref_47 '400': description: Invalid request content: *ref_14 '401': description: Identity could not be verified content: *ref_11 '403': description: Do not have permissions to perform this action content: *ref_12 '500': description: An error has occured content: *ref_13 post: summary: Create pricing intent description: Create a pricing intent. 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 for the identifier. schema: *ref_21 example: 8e03978e-40d5-43e8-bc93-6894a57f9324 requestBody: content: application/json: schema: type: object title: pricing intent description: Object that contains information about a pricing intent. oneOf: *ref_48 examples: createPricingIntent: summary: Create pricing intent description: Create a pricing intent. value: &ref_50 key: Your-Unique-Identifier metadata: internalReference: '2345' country: US version: '4.0' base: addressVerification: 5 annualFee: billInMonth: june amount: 100 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: 1000 returns: 400 unauthorizedReturn: 1999 statement: 800 monthlyMinimum: 20000 accountVerification: 100 discountRateUnder10000: 5.25 discountRateAbove10000: 10 gateway: fees: monthly: 2000 setup: 5000 perTransaction: 2000 perDeviceMonthly: 10 additionalServiceMonthly: 10 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_48 examples: createdPricingIntent: summary: Pricing intent description: Pricing intent value: &ref_49 id: '5' createdDate: '2020-09-22T09:00:00' lastUpdatedDate: '2020-09-22T09:00:00' status: pendingReview key: string metadata: internalReference: '2345' country: US version: '4.0' base: addressVerification: 5 annualFee: billInMonth: december 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 additionalServiceMonthly: 0 headers: location: description: URI reference to created resource. style: simple explode: false schema: *ref_22 '400': description: Validation error content: application/problem+json: schema: type: object properties: *ref_8 required: *ref_9 examples: validationError: summary: Bad Request description: One or more validation errors occurred value: *ref_10 idempotentKeyMissing: summary: Idempotency key missing description: Idempotency key must be supplied value: *ref_23 '401': description: Identity could not be verified content: *ref_11 '403': description: Do not have permissions to perform this action content: *ref_12 '406': description: Not acceptable content: *ref_18 '409': description: Conflict content: application/problem+json: schema: type: object properties: *ref_24 required: *ref_25 examples: idempotentKeyMissing: summary: Idempotency key missing description: Idempotency key must be supplied value: *ref_23 idempotentKeyInUse: summary: Idempotency key in use description: Idempotency key in use value: *ref_26 '500': description: An error has occured content: *ref_13 /pricing-intents/{pricingIntentId}: summary: Provides create/read/updated/delete capabilities for specific pricing intents parameters: - in: path name: pricingIntentId schema: &ref_211 type: string required: true description: Unique identifier of the pricing intent. example: '5' get: summary: Retrieve pricing intent description: Retrieve a specific 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_48 examples: pricingIntent: summary: Pricing intent description: Pricing intent value: *ref_49 '400': description: Invalid request content: *ref_14 '401': description: Identity could not be verified content: *ref_11 '403': description: Do not have permissions to perform this action content: *ref_12 '404': description: Resource not found content: *ref_17 '500': description: An error has occured content: *ref_13 put: summary: Update pricing intent description: Update a pricing intent. 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_48 examples: pricingIntent: summary: Create pricing intent description: Create a pricing intent. value: *ref_50 responses: '204': description: Resource successfully updated '400': description: Invalid request content: *ref_14 '401': description: Identity could not be verified content: *ref_11 '403': description: Do not have permissions to perform this action content: *ref_12 '404': description: Resource not found content: *ref_17 '406': description: Not acceptable content: *ref_18 '500': description: An error has occured content: *ref_13 patch: summary: Partially update pricing intent description: | Partially update an existing pricing intent. Structure your request to follow the RFC 6902 standard. 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 for the identifier. schema: *ref_21 example: 8e03978e-40d5-43e8-bc93-6894a57f9324 requestBody: content: application/json: schema: type: array description: A JSONPatch document as defined by RFC 6902 example: &ref_77 - op: add path: /a/b/c value: - dog - cat - op: remove path: /a/b/c - op: replace path: /a/b/c value: 420 - 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 items: &ref_78 description: JSONPatch document, specified in RFC 6902. required: &ref_278 - op - path properties: &ref_279 op: type: string description: Action that you want to perform on the resource. enum: - add - remove - replace - move - copy - test path: type: string description: | Location of the value that you want to test, add, or remove. If the value for op is `copy` or `move`, the path indicates where you want to move or to copy the value to. The format for this value is JSON Pointer. value: type: object description: Value that you want to test or to add to the resource. from: type: string description: | Location of the value that you want to move or to copy. The format for this value is JSON Pointer. 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_456 - 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_457 - 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_48 examples: pricingIntent: summary: Pricing intent description: Pricing intent value: *ref_49 '400': description: Invalid request content: *ref_14 '401': description: Identity could not be verified content: *ref_11 '403': description: Do not have permissions to perform this action content: *ref_12 '404': description: Resource not found content: *ref_17 '406': description: Not acceptable content: *ref_18 '500': description: An error has occured content: *ref_13 delete: summary: Delete pricing intent description: Delete a 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_11 '403': description: Do not have permissions to perform this action content: *ref_12 '404': description: Resource not found content: *ref_17 '500': description: An error has occured content: *ref_13 /funding-instructions: post: tags: - Funding instructions summary: Create funding instruction description: Create funding instructions to tell us how to divide funds between your funding recipients. 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 for the identifier. schema: *ref_21 example: 8e03978e-40d5-43e8-bc93-6894a57f9324 requestBody: content: application/json: schema: type: object description: Inform the payfac what to do with the specified funds. ** title: funding instruction properties: &ref_51 instructionId: type: integer description: Unique identifier of the funding instruction. example: 12345 readOnly: true createdDate: type: string description: Date that we created the funding instruction. format: datetime example: '2021-09-05T13:15:00.000Z' readOnly: true lastModifiedDate: type: string description: Date of the most recent change to the funding instruction. format: datetime example: '2021-09-06T18:00:00.000Z' readOnly: true status: type: string description: Status of the funding instruction. enum: - accepted - pending - completed readOnly: true merchants: type: array description: Array of merchantInstruction objects. 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 of the merchant. example: '123456' recipients: type: array description: Array of target fundingAccount objects. 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 of the funding account that we pay the funds into. example: 5432425374 paymentMethod: type: string description: Method of payment. enum: - ACH amount: type: object description: Object that contains details about the funds. required: - value properties: value: type: number example: 12350 description: Value of funds in the currency's lowest denomination, for example, cents. currency: description: Currency of the values. The default value is USD. type: string default: USD enum: - USD status: readOnly: true type: string description: Status of the funding instruction. enum: - accepted - pending - released - funded - failed - rejected - onHold metadata: type: object additionalProperties: type: string description: '[Metadata](/api/metadata) object you can use to include custom data with your request.' example: customerId: '2345' link: readOnly: true description: Array of HATEOAS links for viewing a funding account. type: object properties: rel: type: string example: fundingAccount method: type: string example: get href: type: string example: https://api.payroc.com/v1/funding-accounts/5432425374 link: readOnly: true description: Array of HATEOAS links to view the merchant. type: object properties: rel: type: string example: merchant method: type: string example: get href: type: string example: https://api.payroc.com/v1/merchants/123456 required: - merchantId - recipients metadata: type: object additionalProperties: type: string description: '[Metadata](/api/metadata) object you can use to include custom data with your request.' example: internalInstructionRef: abcdef 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_51 examples: newInstructions: summary: New instruction accepted. value: &ref_462 instructionId: 123 createdDate: '2021-09-05T13:15:00.000Z' lastModifiedDate: null status: accepted merchants: - merchantId: '99999' recipients: - status: accepted fundingAccountId: 67890 paymentMethod: ACH amount: value: 12350 currency: USD metadata: customerId: '2345' link: rel: fundingAccount method: get href: https://api.payroc.com/v1/funding-accounts/67890 link: rel: merchant method: get href: https://api.payroc.com/v1/merchants/99999 metadata: instructionRef: abcd headers: location: description: URI reference to created resource. style: simple explode: false schema: *ref_22 '400': description: Validation error. content: application/problem+json: schema: type: object properties: *ref_8 required: *ref_9 examples: validationError: summary: Bad Request description: One or more validation errors occurred value: *ref_10 insufficientFunds: summary: Insufficient funds description: You do not have enough funds to complete the request. value: &ref_52 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_23 fundingAccountsRestrcited: summary: Funding accounts restricted description: Funding accounts restricted. value: &ref_54 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: - fundingAccountId: 1234 message: Funding account on hold '401': description: Identity could not be verified content: *ref_11 '403': description: Do not have permissions to perform this action content: *ref_12 '406': description: Not acceptable content: *ref_18 '409': description: Conflict content: application/problem+json: schema: type: object properties: *ref_24 required: *ref_25 examples: idempotentKeyInUse: summary: Idempotency key in use description: Idempotency key in use value: *ref_26 '500': description: An error has occured content: *ref_13 get: tags: - Funding instructions summary: List funding instructions description: Retrieve a list of funding instructions for a specific date range. operationId: listInstructions parameters: - name: before in: query required: false description: Points to the resource identifier that you want to receive your results before. Typically, this is the first resource on the previous page. explode: false schema: *ref_29 example: '2571' - name: after in: query description: Points to the resource identifier that you want to receive your results after. Typically, this is the last resource on the previous page. schema: *ref_30 example: '8516' - name: limit in: query description: States the total amount of results the response is limited to. schema: *ref_31 example: 25 - name: dateFrom in: query description: Retrieve activity that occured since `dateFrom`. We can return activity from only the last two years. required: true schema: type: string format: date example: '2021-09-01' - name: dateTo in: query required: true description: Retrieve activity that occured before `dateTo`. schema: type: string format: date example: '2021-09-30' 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_32 - 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_51 - type: object properties: link: type: object description: Object that contains information about a HATEOAS link. If we can't match a dispute to a transaction, we don't return a 'link' object. properties: *ref_3 required: *ref_4 example: *ref_5 required: - data examples: listSplitsExample: summary: Paginated instructions list value: &ref_458 limit: 2 count: 2 hasMore: true links: - rel: previous method: get href: https://api.payroc.com/v1/funding-instructions?before=65&limit=2&datefrom=2021-01-01&dateto=2021-01-30 - rel: next method: get href: https://api.payroc.com/v1/funding-instructions?after=66&limit=2&datefrom=2021-01-01&dateto=2021-01-30 data: - instructionId: 65 createdDate: '2021-09-05T13:15:00.000Z' lastModifiedDate: '2021-09-06T18:00:00.000Z' status: completed merchants: - merchantId: '99999' recipients: - status: funded fundingAccountId: 67890 paymentMethod: ACH amount: value: 12350 currency: USD metadata: customerId: '2345' link: rel: fundingAccount method: get href: https://api.payroc.com/v1/funding-accounts/67890 - status: rejected fundingAccountId: 67889 paymentMethod: ACH amount: value: 9000 currency: USD metadata: customerId: '2345' link: rel: fundingAccount method: get href: https://api.payroc.com/v1/funding-accounts/67889 link: rel: merchant method: get href: https://api.payroc.com/v1/merchants/99999 metadata: instrcutionRef: abcd link: rel: fundingInstruction method: get href: https://api.payroc.com/v1/funding-instructions/65 - instructionId: 66 createdDate: '2021-09-06T13:15:00.000Z' lastModifiedDate: null status: accepted merchants: - merchantId: '12345' recipients: - status: accepted fundingAccountId: 54784 paymentMethod: ACH amount: value: 5000 currency: USD metadata: customerId: '5412' link: rel: fundingAccount method: get href: https://api.payroc.com/v1/funding-accounts/54784 link: rel: merchant method: get href: https://api.payroc.com/v1/merchants/12345 - merchantId: 12346 recipients: - status: accepted fundingAccountId: 54784 paymentMethod: ACH amount: value: 1000 currency: USD metadata: customerId: '5412' link: rel: fundingAccount method: get href: https://api.payroc.com/v1/funding-accounts/54784 link: rel: merchant method: get href: https://api.payroc.com/v1/merchants/12346 metadata: instrcutionRef: efgh link: rel: fundingInstruction method: get href: https://api.payroc.com/v1/funding-instructions/66 noActivity: summary: No records found description: Valid request, but no records match the criteria. value: *ref_47 '400': description: Validation error. content: application/problem+json: schema: type: object properties: *ref_8 required: *ref_9 examples: parameterError: 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: 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_11 '403': description: Do not have permissions to perform this action content: *ref_12 '406': description: Not acceptable content: *ref_18 '500': description: An error has occured content: *ref_13 /funding-instructions/{instructionId}: parameters: - name: instructionId in: path required: true description: Unique identifier of the funding instruction. schema: &ref_214 type: integer example: 124567 get: tags: - Funding instructions summary: Retrieve funding instruction operationId: getInstruction description: Retrieve a specific funding instruction. responses: '200': description: Successful request. Returns the requested funding instruction. content: application/json: schema: type: object description: Inform the payfac what to do with the specified funds. ** title: funding instruction properties: *ref_51 '400': description: Validation error. content: application/problem+json: schema: type: object properties: *ref_8 required: *ref_9 examples: instructionIdError: summary: Bad request description: One or more validation errors occurred. value: &ref_53 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_11 '403': description: Do not have permissions to perform this action content: *ref_12 '404': description: Resource not found content: *ref_17 '406': description: Not acceptable content: *ref_18 '500': description: An error has occured content: *ref_13 put: tags: - Funding instructions summary: Update funding instruction operationId: updateInstructions description: Update an existing funding instruction. requestBody: content: application/json: schema: type: object description: Inform the payfac what to do with the specified funds. ** title: funding instruction properties: *ref_51 responses: '204': description: Successful request. We updated the funding instruction. '400': description: Validation error. content: application/problem+json: schema: type: object properties: *ref_8 required: *ref_9 examples: validationError: summary: Bad Request description: One or more validation errors occurred value: *ref_10 insufficientFunds: summary: Insufficient funds description: You do not have enough funds to complete the request. value: *ref_52 canNotBeModified: summary: Cannot be modified description: Resource cannot be modified. value: &ref_55 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_53 fundingAccountsRestrcited: summary: Funding accounts restricted description: Funding accounts restricted. value: *ref_54 '401': description: Identity could not be verified content: *ref_11 '403': description: Do not have permissions to perform this action content: *ref_12 '404': description: Resource not found content: *ref_17 '500': description: An error has occured content: *ref_13 delete: summary: Delete funding instruction description: Delete an existing 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_8 required: *ref_9 examples: canNotBeModified: summary: Cannot be modified description: Resource cannot be modified. value: *ref_55 instructionIdError: summary: Bad request description: One or more validation errors occurred. value: *ref_53 '401': description: Identity could not be verified content: *ref_11 '403': description: Do not have permissions to perform this action content: *ref_12 '404': description: Resource not found content: *ref_17 '500': description: An error has occured content: *ref_13 /funding-balance: get: tags: - Funding activity summary: Retrieve funding balance operationId: getFundingBalance description: Retrieve the balance of funds that are available for each merchant. parameters: - name: before in: query required: false description: Points to the resource identifier that you want to receive your results before. Typically, this is the first resource on the previous page. explode: false schema: *ref_29 example: '2571' - name: after in: query description: Points to the resource identifier that you want to receive your results after. Typically, this is the last resource on the previous page. schema: *ref_30 example: '8516' - name: limit in: query description: States the total amount of results the response is limited to. schema: *ref_31 example: 25 - name: merchantId in: query required: false description: Unique identifier of the merchant. schema: type: string example: '123456789' responses: '200': description: Successful request. Returns the 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_32 - 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_280 merchantId: type: string description: Unique Identifier of the merchant. example: '123' funds: type: integer description: Value of funds in the currency's lowest denomination, for example, cents. example: 120000 pending: type: number description: Value of funds that we have not yet sent to funding recipients. We return this value in the currency's lowest denomination, for example, cents. example: 50050 available: type: number description: Value of funds available for funding instructions. We return this value in the currency's lowest denomination, for example, cents. example: 69950 currency: type: string description: Currency of the values. The default value is USD. example: USD required: - data examples: listSplitsExample: summary: Paginated list of merchant balances description: Paginated list of merchant balances. value: &ref_463 limit: 2 count: 2 hasMore: true links: - rel: previous method: get href: https://api.payroc.com/v1/funding-balance?before=65&limit=2 - rel: next method: get href: https://api.payroc.com/v1/funding-balance?after=66&limit=2 data: - merchantId: '65' funds: 120000 pending: 50050 available: 69950 currency: USD - merchantId: '66' funds: 50000 pending: 0 available: 50000 currency: USD noActivity: summary: No records found description: Valid request, but no records match the criteria. value: *ref_47 '400': description: Validation error. content: application/problem+json: schema: type: object properties: *ref_8 required: *ref_9 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_11 '403': description: Do not have permissions to perform this action content: *ref_12 '406': description: Not acceptable content: *ref_18 '500': description: An error has occured content: *ref_13 /funding-activity: get: tags: - Funding activity summary: List funding activity description: Retrieve funding activity for a specific date range. operationId: getFundingActivity parameters: - name: before in: query required: false description: Points to the resource identifier that you want to receive your results before. Typically, this is the first resource on the previous page. explode: false schema: *ref_29 example: '2571' - name: after in: query description: Points to the resource identifier that you want to receive your results after. Typically, this is the last resource on the previous page. schema: *ref_30 example: '8516' - name: limit in: query description: States the total amount of results the response is limited to. schema: *ref_31 example: 25 - name: dateFrom in: query description: Retrieve activity that occured since `dateFrom`. We can return activity from only the last two years. required: true schema: &ref_212 type: string format: date example: '2021-09-01' - name: dateTo in: query required: true description: Retrieve activity that occured before `dateTo`. schema: &ref_213 type: string format: date example: '2021-09-30' - name: merchantId in: query required: false description: Unique identifier of the merchant. schema: type: string example: '123456789' responses: '200': description: Successful request. Returns all available funding activity for the date range. 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_32 - type: object properties: data: type: array description: Array of activityRecord objects. items: type: object description: Array of activityRecord objects. title: activity record properties: &ref_281 id: type: integer description: Unique identifier of the activity record. example: 12345 date: type: string format: datetime example: '2021-01-01T19:32:00.000Z' description: Date of the transaction. merchant: type: string description: Name of the merchant that the activity applies to. example: Doe Hot Dogs recipient: type: string description: Recipient of the credit. description: type: string example: Sales description: Description of the activity. amount: type: number example: 20000 description: Total fund amount of the transaction. This is returned in the lowest unit of currency. type: type: string description: Payment type. enum: - credit - debit currency: type: string description: Currency of all values. example: USD required: &ref_282 - id - date - recipient - merchant - description - amount - type - currency required: - data examples: paginatedList: summary: Paginated activity records description: Valid payfac account with activity for date range. value: &ref_464 limit: 10 count: 10 hasMore: true links: - rel: previous method: get href: https://api.payroc.com/v1/funding-activity?before=11&limit=10&datefrom=2021-01-01&dateto=2021-01-30 - rel: next method: get href: https://api.payroc.com/v1/funding-activity?after=20&limit=10&datefrom=2021-01-01&dateto=2021-01-30 data: - id: '11' date: '2021-01-01T17:00:00.000Z' merchant: Doe Hot Dogs description: sales type: credit amount: 20000 currency: USD - id: '12' date: '2021-01-01T19:32:00.000Z' merchant: Doe Hot Dogs description: sales type: credit amount: 50000 currency: USD - id: '13' date: '2021-01-01T17:00:00.000Z' merchant: Doe Hot Dogs recipient: Doe Hot Dogs description: payment type: debit amount: 10000 currency: USD - id: '14' date: '2021-01-01T17:00:00.000Z' merchant: Doe Hot Dogs recipient: Payroc description: Interchange Fees type: debit amount: 500 currency: USD - id: '15' date: '2021-01-03T09:10:00.000Z' merchant: Doe Hot Dogs description: sales type: credit amount: 30000 currency: USD - id: '16' date: '2021-01-10T17:00:00.000Z' merchant: Janes shoe laces LTD description: adjustment type: credit amount: 500 currency: USD - id: '17' date: '2021-01-10T17:00:00.000Z' merchant: Janes shoe laces LTD recipient: Payroc description: Interchange Fees type: debit amount: 500 currency: USD - id: '18' date: '2021-01-15T17:00:00.000Z' merchant: Doe Hot Dogs recipient: Payroc description: Charge back type: debit amount: 1000 currency: USD - id: '19' date: '2021-01-17T17:00:00.000Z' merchant: Janes shoe laces LTD description: sales type: credit amount: 50000 currency: USD - id: '20' date: '2021-01-26T17:00:00.000Z' merchant: Doe Hot Dogs recipient: Mr Payfac corp description: payment type: debit amount: 5000 currency: USD noActivity: summary: No records found description: Valid request, but no records match the criteria. value: *ref_47 '400': description: Validation error. content: application/problem+json: schema: type: object properties: *ref_8 required: *ref_9 examples: parameterError: summary: Bad request description: One or more validation errors occurred. value: &ref_459 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_460 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_461 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_11 '403': description: Do not have permissions to perform this action content: *ref_12 '406': description: Not acceptable content: *ref_18 '500': description: An error has occured content: *ref_13 /batches: get: tags: - Settlement summary: List batches description: Retrieve batch data for a specific date. operationId: getbatches parameters: - name: before in: query required: false description: Points to the resource identifier that you want to receive your results before. Typically, this is the first resource on the previous page. explode: false schema: *ref_29 example: '2571' - name: after in: query description: Points to the resource identifier that you want to receive your results after. Typically, this is the last resource on the previous page. schema: *ref_30 example: '8516' - name: limit in: query description: States the total amount of results the response is limited to. schema: *ref_31 example: 25 - name: date in: query required: true description: Date that the merchant submitted the batch. The format of this value is **YYYY-MM-DD**. schema: type: string format: date example: '2021-09-05' - name: merchantId in: query description: Unique identifier of the merchant. schema: &ref_58 type: string example: '4525644354' 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_32 - type: object properties: data: type: array description: Array of batch objects. items: type: object title: batch properties: &ref_56 batchId: type: integer description: Unique identifier of 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: '2021-09-05' 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-01-30' lastModifiedDate: type: string format: date description: Date that the batch was last changed. The format of this value is **YYYY-MM-DD**. example: '2024-01-30' saleAmount: type: integer description: Total value of sales. We return the value in the currency's lowest denomination, for example, cents. heldAmount: type: integer description: Total value of authorizations. We return the value in the currency's lowest denomination, for example, cents. returnAmount: type: integer description: Total value of returns. 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. merchant: type: object title: merchant summary description: Object that contains information about the merchant. properties: &ref_59 merchantId: type: string description: Unique identifier of the merchant. example: '4525644354' doingBusinessAs: type: string description: Legal name that the business operates as. example: Doe Hot Dogs link: type: object description: Object that contains information about a HATEOAS link. If we can't match a dispute to a transaction, we don't return a 'link' object. properties: *ref_3 required: *ref_4 example: *ref_5 example: &ref_60 merchantId: '4525644354' doingBusinessAs: Doe Hot Dogs link: rel: merchant method: get href: https://api.payroc.com/v1/merchants/4525644354 links: type: array items: type: object description: Object that contains information about a HATEOAS link. If we can't match a dispute to a transaction, we don't return a 'link' object. properties: *ref_3 required: *ref_4 example: *ref_5 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_465 limit: 2 count: 2 hasMore: true links: - rel: previous method: get href: https://api.payroc.com/v1/batches?before=65&limit=2&date=2021-01-01 - rel: next method: get href: https://api.payroc.com/v1/batches?after=66&limit=2&&date=2021-01-01 data: - batchId: 65 date: '2021-01-01' createdDate: '2021-09-05' lastModifiedDate: '2021-09-06' saleAmount: 100 heldAmount: 0 returnAmount: 0 transactionCount: 10 currency: USD merchant: merchantId: '4525644354' doingBusinessAs: Pizza Doe link: rel: merchant method: get href: https://api.payroc.com/v1/merchants/4525644354 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: '2021-01-01' createdDate: '2021-09-05' lastModifiedDate: '2021-09-06' saleAmount: 76 heldAmount: 0 returnAmount: 12 transactionCount: 10 currency: USD merchant: merchantId: '987654321' doingBusinessAs: Joe Bloggs Shoes link: rel: merchant method: get href: https://api.payroc.com/v1/merchants/987654321 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_47 '400': description: Validation error content: application/problem+json: schema: type: object properties: *ref_8 required: *ref_9 examples: parameterError: summary: Bad Request description: One or more validation errors occurred value: &ref_61 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_62 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_57 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_11 '403': description: Do not have permissions to perform this action content: *ref_12 '406': description: Not acceptable content: *ref_18 '500': description: An error has occured content: *ref_13 /batches/{batchId}: get: tags: - Settlement summary: Retrieve batch description: Retrieve a specific batch. operationId: getbatch parameters: - name: batchId description: Unique identifier of the batch. in: path required: true style: simple schema: &ref_215 type: integer example: 12345 responses: '200': description: Successful request. Returns the requested batch. content: application/json: schema: type: object title: batch properties: *ref_56 '400': description: Validation error content: application/problem+json: schema: type: object properties: *ref_8 required: *ref_9 examples: idError: summary: Bad Request description: One or more validation errors occurred value: *ref_57 '401': description: Identity could not be verified content: *ref_11 '403': description: Do not have permissions to perform this action content: *ref_12 '404': description: Resource not found content: *ref_17 '406': description: Not acceptable content: *ref_18 '500': description: An error has occured content: *ref_13 /transactions: get: tags: - Settlement summary: List transactions description: Retrieve a list of transactions. operationId: getTransactions parameters: - name: before in: query required: false description: Points to the resource identifier that you want to receive your results before. Typically, this is the first resource on the previous page. explode: false schema: *ref_29 example: '2571' - name: after in: query description: Points to the resource identifier that you want to receive your results after. Typically, this is the last resource on the previous page. schema: *ref_30 example: '8516' - name: limit in: query description: States the total amount of results the response is limited to. schema: *ref_31 example: 25 - name: date in: query required: true description: Date to retrieve results from. The format of this value is **YYYY-MM-DD**. You must provide either the 'batchId' or the 'date'. schema: &ref_64 type: string format: date example: '2021-09-05' - name: batchId in: query required: true description: Unique identifier of the batch. You must provide either the 'batchId' or the 'date'. schema: &ref_65 type: integer example: 12345 - name: merchantId in: query description: Unique identifier of the merchant. schema: *ref_58 example: '4525644354' - name: transactionType in: query required: false description: Type of transaction. schema: &ref_216 type: string enum: - Capture - Return 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_32 - 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_63 transactionId: type: integer description: Unique identifier of the transaction. If we can't match a dispute to a transaction, we don't return 'transactionID' or a 'link' object. example: 12345 nullable: true 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: '2021-01-01' amount: type: integer description: Transaction amount. We return the value in the currency's lowest denomination, for example, cents. example: 25000 entryMethod: type: string 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. nullable: true enum: - barcodeRead - smartChipRead - swipedOriginUnknown - contactlessChip - ecommerce - manuallyEntered - manuallyEnteredFallback - swiped - swipedFallback - swipedError - scannedCheckReader - credentialOnFile - unknown createdDate: type: string format: date description: Date that we received the transaction. The format of this value is **YYYY-MM-DD**. example: '2024-01-30' lastModifiedDate: type: string format: date description: Date that the transaction was last changed. The format of this value is **YYYY-MM-DD**. example: '2024-01-30' status: type: string description: Indicates the status of the transaction. enum: - fullSuspense - heldAudited - heldReleasedAudited - holdForSettlement30Days - holdForSettlementDuplicate - holdLongTerm - paid - paidByThirdParty - partialRelease - pull - release - new - held - unknown cashbackAmount: type: integer description: Cashback amount. We return the value in the currency's lowest denomination, for example, cents. 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. transactionFee: type: integer description: Interchange fee for the transaction. We return the value in the currency's lowest denomination, for example, cents. currency: type: string description: Currency of the transaction. merchant: type: object title: merchant summary description: Object that contains information about the merchant. properties: *ref_59 example: *ref_60 settled: type: object title: settlement summary description: Object that contains information about the settlement. properties: &ref_283 settledBy: type: string description: Processor that settled the transaction. achDate: type: string format: date description: Date that the processor settled the transaction. The format of this value is **YYYY-MM-DD**. example: '2021-09-05' batch: type: object 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. nullable: true properties: &ref_66 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: '2021-09-05' cycle: type: string description: Indicates the cycle that contains the batch. example: am link: type: object description: Object that contains information about a HATEOAS link. If we can't match a dispute to a transaction, we don't return a 'link' object. properties: *ref_3 required: *ref_4 example: *ref_5 card: type: object title: card summary description: Object that contains information about the card. properties: &ref_67 cardNumber: type: string description: Card number. We mask the number except for the first six digits and the last four digits. example: 123456**********4124 type: type: string description: Card type. If we can't match a dispute to a transaction, we don't return a 'type' object. nullable: true enum: - visa - masterCard - discover - debit - ebt - wrightExpress - voyager - amex - privateLabel - storedValue - discoverRetained - jcbNonSettled - dinersClub - amexOptBlue - fuelman - unknown cvvPresenceIndicator: type: boolean description: Indicates if the cardholder provided the CVV. avsRequest: type: boolean description: Indicates if the AVS was used to verify the cardholder's address. avsResponse: type: string description: Response from the AVS. authorization: type: object title: authorization summary description: Object that contains information about the authorization. properties: &ref_284 authorizationId: type: integer description: Unique identifier of the authorization. example: 12345 code: type: string description: | Authorization code. **Note:** For returns, the card brands may not provide an authorization code. amount: type: integer description: Authorization amount. We return the value in the currency's lowest denomination, for example, cents. avsResponseCode: type: string description: Response code that indicates if the address matches the address registered to the customer. link: type: object description: Object that contains information about a HATEOAS link. If we can't match a dispute to a transaction, we don't return a 'link' object. properties: *ref_3 required: *ref_4 example: *ref_5 required: - data examples: paginatedList: summary: Paginated transactions value: &ref_466 limit: 2 count: 1 hasMore: false links: - rel: previous method: get href: https://api.payroc.com/v1/transctions?before=65&limit=2&date=2021-01-01 data: - transactionId: 65 type: capture date: '2021-01-01' amount: 25000 entryMethod: ecommerce createdDate: '2021-09-05' lastModifiedDate: '2021-09-06' status: paid cashbackAmount: 0 interchange: basisPoint: 0 transactionFee: 0 currency: USD merchant: merchantId: '4525644354' doingBusinessAs: Pizza Doe link: rel: merchant method: get href: https://api.payroc.com/v1/merchants/4525644354 settled: settledBy: 3rd party achDate: '2021-09-05' batch: batchId: 12 date: '2021-01-01' 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: '' authorization: authorizationId: 12345 code: ABCDE amount: 100 avsResponseCode: '' link: rel: authorization method: get href: https://api.payroc.com/v1/authorizations/12345 noActivity: summary: No records found description: Valid request, but no records match the criteria. value: *ref_47 '400': description: Validation error content: application/problem+json: schema: type: object properties: *ref_8 required: *ref_9 examples: parameterError: summary: Bad Request description: One or more validation errors occurred value: *ref_61 paginationError: summary: Bad Request description: One or more validation errors occurred value: *ref_62 '401': description: Identity could not be verified content: *ref_11 '403': description: Do not have permissions to perform this action content: *ref_12 '406': description: Not acceptable content: *ref_18 '500': description: An error has occured content: *ref_13 /transactions/{transactionId}: get: tags: - Settlement summary: Retrieve transaction description: Retrieve a specific transaction. operationId: gettransaction parameters: - name: transactionId description: Unique identifier of the transaction. in: path required: true style: simple schema: &ref_217 type: integer example: 12345 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_63 '400': description: Validation error content: application/problem+json: schema: type: object properties: *ref_8 required: *ref_9 examples: transactionIdError: summary: Bad Request description: One or more validation errors occurred value: &ref_467 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_11 '403': description: Do not have permissions to perform this action content: *ref_12 '404': description: Resource not found content: *ref_17 '406': description: Not acceptable content: *ref_18 '500': description: An error has occured content: *ref_13 /authorizations: get: tags: - Settlement summary: List authorizations description: Retrieve a list of authorizations. operationId: getAuthorizations parameters: - name: before in: query required: false description: Points to the resource identifier that you want to receive your results before. Typically, this is the first resource on the previous page. explode: false schema: *ref_29 example: '2571' - name: after in: query description: Points to the resource identifier that you want to receive your results after. Typically, this is the last resource on the previous page. schema: *ref_30 example: '8516' - name: limit in: query description: States the total amount of results the response is limited to. schema: *ref_31 example: 25 - name: date in: query required: true description: Date to retrieve results from. The format of this value is **YYYY-MM-DD**. You must provide either the 'batchId' or the 'date'. schema: *ref_64 example: '2021-09-05' - name: batchId in: query required: true description: Unique identifier of the batch. You must provide either the 'batchId' or the 'date'. schema: *ref_65 example: 12345 - name: merchantId in: query description: Unique identifier of the merchant. schema: *ref_58 example: '4525644354' 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_32 - 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_68 authorizationId: type: integer description: Unique identifier of 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: Code that indicates the response 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. batch: type: object 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. nullable: true properties: *ref_66 card: type: object title: card summary description: Object that contains information about the card. properties: *ref_67 merchant: type: object title: merchant summary description: Object that contains information about the merchant. properties: *ref_59 example: *ref_60 transaction: type: object title: transaction summary description: Object that contains summary information about the transaction. properties: &ref_69 transactionId: type: integer description: Unique identifier of the transaction. If we can't match a dispute to a transaction, we don't return 'transactionID' or a 'link' object. example: 12345 nullable: true 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: '2021-01-01' entryMethod: type: string 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. nullable: true enum: - barcodeRead - smartChipRead - swipedOriginUnknown - contactlessChip - ecommerce - manuallyEntered - manuallyEnteredFallback - swiped - swipedFallback - swipedError - scannedCheckReader - credentialOnFile - unknown amount: type: integer description: Transaction amount. We return the value in the currency's lowest denomination, for example, cents. example: 25000 link: type: object description: Object that contains information about a HATEOAS link. If we can't match a dispute to a transaction, we don't return a 'link' object. properties: *ref_3 required: *ref_4 example: *ref_5 required: - data examples: paginatedList: summary: Paginated authorizations value: &ref_468 limit: 2 count: 1 hasMore: false links: - rel: previous method: get href: https://api.payroc.com/v1/authorizations?before=65&limit=2&date=2021-01-01 data: - authorizationId: 65 createdDate: '2021-09-05' lastModifiedDate: '2021-09-06' authorizationResponse: successful preauthorizationRequestAmount: 10000 currency: USD merchant: merchantId: '4525644354' doingBusinessAs: Pizza Doe link: rel: merchant method: get href: https://api.payroc.com/v1/merchants/4525644354 batch: batchId: 12 date: '2021-01-01' 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: '' transaction: transactionId: 12345 type: capture date: '' 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_47 '400': description: Validation error content: application/problem+json: schema: type: object properties: *ref_8 required: *ref_9 examples: parameterError: summary: Bad Request description: One or more validation errors occurred value: *ref_61 paginationError: summary: Bad Request description: One or more validation errors occurred value: *ref_62 '401': description: Identity could not be verified content: *ref_11 '403': description: Do not have permissions to perform this action content: *ref_12 '406': description: Not acceptable content: *ref_18 '500': description: An error has occured content: *ref_13 /authorizations/{authorizationId}: get: tags: - Settlement summary: Retrieve authorization description: Retrieve a specific authorization. operationId: getAuthorization parameters: - name: authorizationId description: Unique identifier of the authorization. in: path required: true style: simple schema: &ref_218 type: integer example: 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_68 '400': description: Invalid request content: *ref_14 '401': description: Identity could not be verified content: *ref_11 '403': description: Do not have permissions to perform this action content: *ref_12 '404': description: Resource not found content: *ref_17 '406': description: Not acceptable content: *ref_18 '500': description: An error has occured content: *ref_13 /disputes: get: tags: - Settlement summary: List disputes description: Retrieve a list of disputes. operationId: getdisputes parameters: - name: before in: query required: false description: Points to the resource identifier that you want to receive your results before. Typically, this is the first resource on the previous page. explode: false schema: *ref_29 example: '2571' - name: after in: query description: Points to the resource identifier that you want to receive your results after. Typically, this is the last resource on the previous page. schema: *ref_30 example: '8516' - name: limit in: query description: States the total amount of results the response is limited to. schema: *ref_31 example: 25 - name: date in: query required: true description: Date that the dispute was submitted. schema: type: string format: date example: '2021-09-05' - name: merchantId in: query description: Unique identifier of the merchant. schema: *ref_58 example: '4525644354' 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_32 - 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_285 disputeId: type: integer description: Unique identifier of the dispute. example: 12345 disputeType: type: string description: Type of dispute. enum: - prearbitration - issuerReversal - firstDisputeWithReversal - firstDispute currentStatus: allOf: - type: object title: dispute status description: Object that contains information about the current status of the dispute. properties: &ref_70 disputeStatusId: type: integer description: Unique identifier of the dispute status. example: 12345 status: type: string description: Status of the dispute. 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 changed. The format of this value is **YYYY-MM-DD**. example: '2024-02-01' - type: object properties: link: type: object description: Object that contains information about a HATEOAS link. If we can't match a dispute to a transaction, we don't return a 'link' object. properties: *ref_3 required: *ref_4 example: *ref_5 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. currency: type: string description: Currency of the dispute. card: type: object title: card summary description: Object that contains information about the card. properties: *ref_67 merchant: type: object title: merchant summary description: Object that contains information about the merchant. properties: *ref_59 example: *ref_60 transaction: type: object title: transaction summary description: Object that contains summary information about the transaction. properties: *ref_69 required: - data examples: paginatedList: summary: Paginated disputes value: &ref_469 limit: 2 count: 1 hasMore: false links: - rel: previous method: get href: https://api.payroc.com/v1/disputes?before=65&limit=2&date=2021-01-01 data: - disputeId: 65 disputeType: firstDispute currentStatus: disputeStatusId: 123 status: new statusDate: '2021-09-06' link: rel: statuses method: get href: https://api.payroc.com/v1/disputes/12345/statuses createdDate: '2021-09-05' lastModifiedDate: '2021-09-06' receivedDate: '' description: '' referenceNumber: '35435435' disputeAmount: 1000 feeAmount: 100 firstDispute: true authorizationCode: '574254' currency: USD merchant: merchantId: '4525644354' doingBusinessAs: Pizza Doe link: rel: merchant method: get href: https://api.payroc.com/v1/merchants/4525644354 card: cardNumber: 12456**********4124 type: visa cvvPresenceIndicator: true avsRequest: true avsResponse: '' transaction: transactionId: 12345 type: capture date: '' 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_47 '400': description: Validation error content: application/problem+json: schema: type: object properties: *ref_8 required: *ref_9 examples: parameterError: summary: Bad Request description: One or more validation errors occurred value: *ref_61 paginationError: summary: Bad Request description: One or more validation errors occurred value: *ref_62 '401': description: Identity could not be verified content: *ref_11 '403': description: Do not have permissions to perform this action content: *ref_12 '406': description: Not acceptable content: *ref_18 '500': description: An error has occured content: *ref_13 /disputes/{disputeId}/statuses: get: tags: - Settlement summary: List dispute statuses description: Retrieve the status history for a specific dispute. operationId: getdisputesStatuses parameters: - name: disputeId description: Unique identifier of the dispute. in: path required: true style: simple schema: &ref_219 type: integer example: 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_70 '400': description: Validation error content: application/problem+json: schema: type: object properties: *ref_8 required: *ref_9 examples: parameterError: summary: Bad Request description: One or more validation errors occurred value: *ref_61 '401': description: Identity could not be verified content: *ref_11 '403': description: Do not have permissions to perform this action content: *ref_12 '404': description: Resource not found content: *ref_17 '406': description: Not acceptable content: *ref_18 '500': description: An error has occured content: *ref_13 /processing-terminals/{processingTerminalId}/payment-plans: post: tags: - Payment plans summary: Create payment plan description: Create a new payment plan. 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 for the identifier. schema: *ref_21 example: 8e03978e-40d5-43e8-bc93-6894a57f9324 - name: processingTerminalId in: path required: true description: Unique identifier that our gateway assigned to the terminal. schema: maxLength: 50 minLength: 4 type: string requestBody: content: application/json: schema: required: &ref_74 - paymentPlanId - name - currency - frequency - onDelete - onUpdate - type type: object properties: &ref_75 paymentPlanId: maxLength: 48 minLength: 1 type: string description: Unique identifier that the merchant assigns to the payment plan. processingTerminalId: maxLength: 50 minLength: 4 type: string readOnly: true description: Unique identifier of the terminal that the payment plan is assigned to. name: maxLength: 128 minLength: 5 type: string description: Name of the payment plan. description: maxLength: 128 minLength: 0 type: string description: Description of the payment plan. currency: type: string description: | Currency code for the payment plan. This code follows the ISO 4217 standard. enum: - AED - AFN - ALL - AMD - ANG - AOA - ARS - AUD - AWG - AZN - BAM - BBD - BDT - BGN - BHD - BIF - BMD - BND - BOB - BOV - BRL - BSD - BTN - BWP - BYR - BZD - CAD - CDF - CHE - CHF - CHW - CLF - CLP - CNY - COP - COU - CRC - CUC - CUP - CVE - CZK - DJF - DKK - DOP - DZD - EGP - ERN - ETB - EUR - FJD - FKP - GBP - GEL - GHS - GIP - GMD - GNF - GTQ - GYD - HKD - HNL - HRK - HTG - HUF - IDR - ILS - INR - IQD - IRR - ISK - JMD - JOD - JPY - KES - KGS - KHR - KMF - KPW - KRW - KWD - KYD - KZT - LAK - LBP - LKR - LRD - LSL - LTL - LVL - LYD - MAD - MDL - MGA - MKD - MMK - MNT - MOP - MRO - MRU - MUR - MVR - MWK - MXN - MXV - MYR - MZN - NAD - NGN - NIO - NOK - NPR - NZD - OMR - PAB - PEN - PGK - PHP - PKR - PLN - PYG - QAR - RON - RSD - RUB - RWF - SAR - SBD - SCR - SDG - SEK - SGD - SHP - SLL - SOS - SRD - SSP - STD - STN - SVC - SYP - SZL - THB - TJS - TMT - TND - TOP - TRY - TTD - TWD - TZS - UAH - UGX - USD - USN - USS - UYI - UYU - UZS - VEF - VES - VND - VUV - WST - XAF - XCD - XOF - XPF - YER - ZAR - ZMW - ZWL setupOrder: type: object description: Object that contains information about the initial cost that a customer pays to set up the subscription. allOf: &ref_286 - type: object properties: &ref_73 amount: type: integer format: int64 description: Total amount before surcharges. The value is in the currency's lowest denomination, for example, cents. description: maxLength: 1024 minLength: 0 type: string description: Description of the transaction. breakdown: required: &ref_71 - subtotal type: object description: | Object that contains information about the taxes that apply to the transaction. properties: &ref_72 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. taxes: type: array description: Array of tax objects. items: required: &ref_102 - name - rate type: object properties: &ref_103 name: maxLength: 64 minLength: 1 type: string description: Name of the tax. rate: maximum: 99.99999 exclusiveMaximum: false minimum: 0 exclusiveMinimum: false type: number format: double description: Tax percentage for the transaction. amount: minimum: 0 exclusiveMinimum: true 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. - type: object properties: amount: type: integer format: int64 description: Total amount before surcharges. The value is in the currency's lowest denomination, for example, cents. description: maxLength: 1024 minLength: 1 type: string description: Description of the transaction. breakdown: required: *ref_71 type: object description: | Object that contains information about the taxes that apply to the transaction. properties: *ref_72 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_81 - type: object properties: *ref_73 - type: object properties: amount: type: integer format: int64 description: Total amount before surcharges. The value is in the currency's lowest denomination, for example, cents. description: maxLength: 1024 minLength: 1 type: string description: Description of the transaction. breakdown: required: *ref_71 type: object description: | Object that contains information about the taxes that apply to the transaction. properties: *ref_72 length: minimum: 0 default: 0 type: integer format: int32 description: | Object that contains information about the cost of each payment. To indicate that the payment plan should run indefinitely, send a value of `0`. 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 frequency: type: string description: Indicates how often the merchant or the terminal collects a payment from the customer. enum: - weekly - fortnightly - monthly - quarterly - yearly 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 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 examples: paymentPlanRequest: summary: Payment Plan description: Payment Plan value: &ref_471 paymentPlanId: 1001_yearly_plan name: 1001 yearly payment plan description: 1001 yearly payment plan currency: EUR setupOrder: amount: 1010 description: payment plan setup order breakdown: subtotal: 1000 taxes: - name: VAT rate: 1 recurringOrder: amount: 1010 description: payment plan setup order breakdown: subtotal: 1000 taxes: - name: VAT rate: 1 length: 5 type: automatic frequency: yearly onUpdate: continue onDelete: complete required: true responses: '201': description: Successful request. We created the payment plan. content: application/json: schema: required: *ref_74 type: object properties: *ref_75 examples: createdPaymentPlan: summary: Payment Plan description: Payment Plan value: &ref_76 paymentPlanId: 1001_yearly_plan processingTerminalId: '1001' name: 1001 yearly payment plan description: 1001 yearly payment plan currency: EUR setupOrder: amount: 1010 description: payment plan setup order breakdown: subtotal: 1000 taxes: - name: VAT rate: 1 recurringOrder: amount: 1010 description: payment plan recurring order breakdown: subtotal: 1000 taxes: - name: VAT rate: 1 length: 5 type: automatic frequency: yearly onUpdate: continue onDelete: complete headers: location: description: URI reference to created resource. style: simple explode: false schema: *ref_22 '400': description: Validation error content: application/problem+json: schema: type: object properties: *ref_8 required: *ref_9 examples: validationError: summary: Bad Request description: One or more validation errors occurred value: *ref_10 idempotentKeyMissing: summary: Idempotency key missing description: Idempotency key must be supplied value: *ref_23 idempotentKeyInUse: summary: Idempotency key in use description: Idempotency key in use value: *ref_26 '401': description: Identity could not be verified content: *ref_11 '403': description: Do not have permissions to perform this action content: *ref_12 '406': description: Not acceptable content: *ref_18 '409': description: Conflict content: &ref_79 application/problem+json: schema: type: object properties: *ref_24 required: *ref_25 examples: resourceExists: summary: Resource already exists description: Resource already exists value: &ref_472 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_80 application/problem+json: schema: type: object properties: &ref_228 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_229 - type - title - status - detail examples: unsupportedMediaType: summary: Unsupported media type description: The payload is in an unsupported format. value: &ref_473 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_13 get: tags: - Payment plans summary: List payment plans description: Retrieve a list of payment plans. operationId: listPaymentPlans parameters: - name: processingTerminalId in: path required: true description: Unique identifier that our gateway assigned to the terminal. schema: maxLength: 50 minLength: 4 type: string - name: before in: query required: false description: Points to the resource identifier that you want to receive your results before. Typically, this is the first resource on the previous page. explode: false schema: *ref_29 example: '2571' - name: after in: query description: Points to the resource identifier that you want to receive your results after. Typically, this is the last resource on the previous page. schema: *ref_30 example: '8516' - name: limit in: query description: States the total amount of results the response is limited to. schema: *ref_31 example: 25 responses: '200': description: Successful request. Returns a paginated list of payment plans. content: application/json: schema: required: &ref_287 - count - data - hasMore - limit type: object allOf: &ref_288 - type: object description: Contains the pagination properties that you use to navigate through a list of results. properties: *ref_32 - type: object properties: data: type: array description: Array of paymentPlan objects. items: required: *ref_74 type: object properties: *ref_75 examples: paginatedResults: summary: Payment Plan description: Payment Plan value: &ref_470 limit: 2 count: 2 hasMore: true data: - paymentPlanId: 1001_yearly_plan processingTerminalId: '1001' name: 1001 yearly plan description: payment plan, setup order with taxes currency: EUR length: 0 type: automatic frequency: yearly onUpdate: continue onDelete: complete - paymentPlanId: 1001_payment_plan_premium processingTerminalId: '1001' name: 1001 payment plan premium description: a template payment plan for premium users currency: EUR length: 0 type: automatic frequency: yearly onUpdate: continue onDelete: complete links: - rel: next method: get href: https://api.payroc.com/v1/processing-terminals/1001/payment-plans?limit=2&after=M4MY49Z5JB - rel: previous method: get href: https://api.payroc.com/v1/processing-terminals/1001/payment-plans?limit=2&before=GKB49GZ6DL noActivity: summary: No records found description: Valid request, but no records match the criteria. value: *ref_47 '400': description: Invalid request content: *ref_14 '401': description: Identity could not be verified content: *ref_11 '403': description: Do not have permissions to perform this action content: *ref_12 '406': description: Not acceptable content: *ref_18 '500': description: An error has occured content: *ref_13 /processing-terminals/{processingTerminalId}/payment-plans/{paymentPlanId}: get: tags: - Payment plans summary: Retrieve payment plan description: Retrieve a specific payment plan. operationId: getPaymentPlan parameters: - name: processingTerminalId in: path required: true description: Unique identifier that our gateway assigned to the terminal. schema: maxLength: 50 minLength: 4 type: string - name: paymentPlanId in: path description: Unique identifier that the merchant assigned to the payment plan. required: true schema: maxLength: 48 minLength: 1 type: string responses: '200': description: Successful request. Returns the requested payment plan. content: application/json: schema: required: *ref_74 type: object properties: *ref_75 examples: paymentPlan: summary: Payment Plan description: Payment Plan value: *ref_76 '400': description: Invalid request content: *ref_14 '401': description: Identity could not be verified content: *ref_11 '403': description: Do not have permissions to perform this action content: *ref_12 '404': description: Resource not found content: *ref_17 '406': description: Not acceptable content: *ref_18 '500': description: An error has occured content: *ref_13 patch: tags: - Payment plans summary: Update payment plan description: | Make changes to an existing payment plan. Structure your request to follow the RFC 6902 standard. 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 for the identifier. schema: *ref_21 example: 8e03978e-40d5-43e8-bc93-6894a57f9324 - name: processingTerminalId in: path required: true description: Unique identifier that our gateway assigned to the terminal. schema: maxLength: 50 minLength: 4 type: string - name: paymentPlanId in: path description: Unique identifier that the merchant assigned to the payment plan. required: true schema: maxLength: 48 minLength: 1 type: string requestBody: content: application/json: schema: type: array description: A JSONPatch document as defined by RFC 6902 example: *ref_77 items: *ref_78 required: true responses: '200': description: Successful request. We updated the payment plan. content: application/json: schema: required: *ref_74 type: object properties: *ref_75 examples: paymentPlan: summary: Payment Plan description: Payment Plan value: *ref_76 '400': description: Invalid request content: *ref_14 '401': description: Identity could not be verified content: *ref_11 '403': description: Do not have permissions to perform this action content: *ref_12 '404': description: Resource not found content: *ref_17 '406': description: Not acceptable content: *ref_18 '409': description: Conflict content: *ref_79 '415': description: Unsupported media type content: *ref_80 '500': description: An error has occured content: *ref_13 delete: tags: - Payment plans summary: Delete payment plan description: | Delete an existing payment plan. **Note:** After you delete a payment plan, you can't reuse the paymentPlanId. operationId: deletePaymentPlan parameters: - name: processingTerminalId in: path required: true description: Unique identifier that our gateway assigned to the terminal. schema: maxLength: 50 minLength: 4 type: string - name: paymentPlanId in: path description: Unique identifier that the merchant assigned to the payment plan. required: true schema: maxLength: 48 minLength: 1 type: string responses: '204': description: Successful request. We deleted the payment plan. '400': description: Invalid request content: *ref_14 '401': description: Identity could not be verified content: *ref_11 '403': description: Do not have permissions to perform this action content: *ref_12 '404': description: Resource not found content: *ref_17 '500': description: An error has occured content: *ref_13 /processing-terminals/{processingTerminalId}/subscriptions: post: tags: - Subscriptions summary: Create subscription description: Create a new subscription. 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 for the identifier. schema: *ref_21 example: 8e03978e-40d5-43e8-bc93-6894a57f9324 - name: processingTerminalId in: path description: Unique identifier that our gateway assigned to the terminal. required: true schema: maxLength: 50 minLength: 4 type: string requestBody: content: application/json: schema: required: &ref_293 - paymentMethod - paymentPlanId - startDate - subscriptionId type: object properties: &ref_294 subscriptionId: maxLength: 48 minLength: 1 type: string description: Unique identifier that the merchant assigned to the subscription. paymentPlanId: maxLength: 48 minLength: 1 type: string description: Unique identifier that the merchant assigned to the payment plan. paymentMethod: type: object description: Object that contains information about the customer's payment details. oneOf: - required: &ref_108 - 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_109 type: type: string description: Method that the payment device used to take the payment. enum: - secureToken accountType: type: string description: | Indicates the customer’s account type. **Note:** Credit card transactions don't require **accountType**. enum: - checking - savings token: maxLength: 19 minLength: 12 type: string description: Unique token that the gateway assigned to the payment details. name: maxLength: 128 minLength: 5 type: string description: | Name of the subscription. This value replaces the name inherited from the payment plan. description: maxLength: 128 minLength: 1 type: string description: | Description of the subscription. This value replaces the description inherited from the payment plan. setupOrder: description: Object that contains information about the initial cost that a customer pays to set up the subscription. type: object allOf: &ref_82 - type: object properties: *ref_73 - type: object properties: orderId: maxLength: 24 minLength: 1 type: string description: A unique identifier assigned by the merchant. amount: type: integer format: int64 description: Total amount before surcharges. The value is in the currency's lowest denomination, for example, cents. description: maxLength: 1024 minLength: 1 type: string description: Description of the transaction. breakdown: required: *ref_71 type: object description: | Object that contains information about the taxes that apply to the transaction. properties: *ref_72 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_81 startDate: type: string format: date description: | Format: **YYYY-MM-DD** Subscription's start date. 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. 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. 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. examples: createSubscription: summary: Subscription description: Subscription value: &ref_475 subscriptionId: 11001_subscription_cinema paymentPlanId: 1001_payment_plan_yearly paymentMethod: type: secureToken token: '2967533500670317' name: subscription from postman description: created through postman for card token setupOrder: amount: 1010 description: setup order breakdown: subtotal: 1000 taxes: - name: VAT rate: 1 orderId: setup order recurringOrder: amount: 1010 description: recurring order breakdown: subtotal: 1000 taxes: - name: VAT rate: 1 startDate: '2023-07-01' endDate: '2025-07-01' length: 2 pauseCollectionFor: 0 required: true responses: '201': description: Successful request. We created the subscription. content: application/json: schema: required: &ref_83 - subscriptionId - processingTerminalId - paymentPlan - secureToken - name - currency - currentState - startDate - type - frequency type: object properties: &ref_84 subscriptionId: maxLength: 48 minLength: 1 type: string description: Unique identifier that the merchant assigned to the subscription. processingTerminalId: maxLength: 50 minLength: 4 type: string description: Unique identifier of the terminal that the subscription is linked to. paymentPlan: required: &ref_289 - name - paymentPlanId type: object properties: &ref_290 paymentPlanId: maxLength: 48 minLength: 1 type: string description: Unique identifier that the merchant assigns to the payment plan. name: maxLength: 128 minLength: 5 type: string description: Name of the payment plan. link: type: object description: Object that contains information about a HATEOAS link. If we can't match a dispute to a transaction, we don't return a 'link' object. properties: *ref_3 required: *ref_4 example: *ref_5 secureToken: required: &ref_86 - customerName - secureTokenId - status - token type: object description: Object that contains information about the secure token. properties: &ref_87 secureTokenId: maxLength: 200 minLength: 1 type: string description: Unique identifier that the merchant assigned to the secure token. customerName: maxLength: 50 minLength: 1 type: string description: Customer's name. 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. 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 link: type: object description: Object that contains information about a HATEOAS link. If we can't match a dispute to a transaction, we don't return a 'link' object. properties: *ref_3 required: *ref_4 example: *ref_5 name: maxLength: 128 minLength: 5 type: string description: Name of the subscription. description: maxLength: 128 minLength: 1 type: string description: Description of the subscription. currency: type: string description: Currency code for the subscription. This code follows the ISO 4217 standard. enum: - AED - AFN - ALL - AMD - ANG - AOA - ARS - AUD - AWG - AZN - BAM - BBD - BDT - BGN - BHD - BIF - BMD - BND - BOB - BOV - BRL - BSD - BTN - BWP - BYR - BZD - CAD - CDF - CHE - CHF - CHW - CLF - CLP - CNY - COP - COU - CRC - CUC - CUP - CVE - CZK - DJF - DKK - DOP - DZD - EGP - ERN - ETB - EUR - FJD - FKP - GBP - GEL - GHS - GIP - GMD - GNF - GTQ - GYD - HKD - HNL - HRK - HTG - HUF - IDR - ILS - INR - IQD - IRR - ISK - JMD - JOD - JPY - KES - KGS - KHR - KMF - KPW - KRW - KWD - KYD - KZT - LAK - LBP - LKR - LRD - LSL - LTL - LVL - LYD - MAD - MDL - MGA - MKD - MMK - MNT - MOP - MRO - MRU - MUR - MVR - MWK - MXN - MXV - MYR - MZN - NAD - NGN - NIO - NOK - NPR - NZD - OMR - PAB - PEN - PGK - PHP - PKR - PLN - PYG - QAR - RON - RSD - RUB - RWF - SAR - SBD - SCR - SDG - SEK - SGD - SHP - SLL - SOS - SRD - SSP - STD - STN - SVC - SYP - SZL - THB - TJS - TMT - TND - TOP - TRY - TTD - TWD - TZS - UAH - UGX - USD - USN - USS - UYI - UYU - UZS - VEF - VES - VND - VUV - WST - XAF - XCD - XOF - XPF - YER - ZAR - ZMW - ZWL setupOrder: description: Object that contains information about the initial cost that a customer pays to set up the subscription. type: object allOf: *ref_82 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_81 currentState: required: &ref_88 - paidInvoices - status type: object properties: &ref_89 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 nextDueDate: type: string description: Date that the merchant collects the next payment. format: date paidInvoices: minimum: 0 type: integer description: Number of payments that the merchant has collected. format: int32 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 description: A snapshot of the subscription's current state. startDate: type: string format: date description: | Format: **YYYY-MM-DD** Subscription's start date. 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. 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. 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 frequency: type: string description: Indicates how often the merchant or the terminal collects a payment from the customer. enum: - weekly - fortnightly - monthly - quarterly - yearly 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. examples: createdSubscription: summary: Subscription description: Subscription value: &ref_85 subscriptionId: 1001_subscription_cinema processingTerminalId: '1001' paymentPlan: paymentPlanId: 1001_paymentplan_yearly name: yearly payment plan link: rel: self method: GET href: https://api.payroc.com/v1/processing-terminals/1001/payment-plans/1001_paymentplan_yearly secureToken: secureTokenId: SecureCard1001 customerName: Joe Bloggs token: '2967533500670317' status: notValidated link: rel: self method: GET href: https://api.payroc.com/v1/processing-terminals/1001/secure-tokens/SecureCard1001 name: avant-garde description: avant-garde cinema subscription currency: EUR setupOrder: orderId: setup-order amount: 1010 description: setup order breakdown: subtotal: 1000 taxes: - name: VAT rate: 1 recurringOrder: amount: 1010 description: recurring order breakdown: subtotal: 1000 taxes: - name: VAT rate: 1 currentState: status: active nextDueDate: '2023-04-25' paidInvoices: 0 outstandingInvoices: 3 startDate: '2023-04-25' endDate: '2025-04-25' length: 24 type: automatic frequency: yearly pauseCollectionFor: 0 headers: location: description: URI reference to created resource. style: simple explode: false schema: *ref_22 '400': description: Validation error content: application/problem+json: schema: type: object properties: *ref_8 required: *ref_9 examples: validationError: summary: Bad Request description: One or more validation errors occurred value: *ref_10 idempotentKeyMissing: summary: Idempotency key missing description: Idempotency key must be supplied value: *ref_23 idempotentKeyInUse: summary: Idempotency key in use description: Idempotency key in use value: *ref_26 '401': description: Identity could not be verified content: *ref_11 '403': description: Do not have permissions to perform this action content: *ref_12 '406': description: Not acceptable content: *ref_18 '409': description: Conflict content: *ref_79 '415': description: Unsupported media type content: *ref_80 '500': description: An error has occured content: *ref_13 get: tags: - Subscriptions summary: List subscriptions description: | List subscriptions linked to a terminal. To filter your results, use the query parameters. operationId: listSubscriptions parameters: - name: processingTerminalId in: path required: true description: Unique identifier that our gateway assigned to the terminal. schema: maxLength: 50 minLength: 4 type: string - name: customerName in: query description: Filter by the customer's name. schema: maxLength: 50 minLength: 1 type: string - name: last4 in: query description: Filter by the last four digits of the card or account number. schema: pattern: '[0-9]{4}' type: string - name: paymentPlan in: query description: Filter by the name of the payment plan. schema: maxLength: 128 minLength: 1 type: string - name: frequency in: query description: Filter by the frequency of subscription payments. schema: type: string enum: - weekly - fortnightly - monthly - quarterly - yearly - name: status in: query description: Filter by the current status of the subscription. schema: type: string enum: - active - completed - suspended - cancelled - name: endDate in: query description: | Format: `YYYY-MM-DD` Filter subscriptions that end on a specific date. schema: type: string format: date - name: nextDueDate in: query description: | Format: `YYYY-MM-DD` Filter subscriptions by the date that the next payment is collected. schema: type: string format: date - name: before in: query required: false description: Points to the resource identifier that you want to receive your results before. Typically, this is the first resource on the previous page. explode: false schema: *ref_29 example: '2571' - name: after in: query description: Points to the resource identifier that you want to receive your results after. Typically, this is the last resource on the previous page. schema: *ref_30 example: '8516' - name: limit in: query description: States the total amount of results the response is limited to. schema: *ref_31 example: 25 responses: '200': description: Successful request. Returns a paginated list of subscriptions. content: application/json: schema: required: &ref_291 - count - data - hasMore - limit type: object allOf: &ref_292 - type: object description: Contains the pagination properties that you use to navigate through a list of results. properties: *ref_32 - type: object properties: data: type: array description: Array of subscriptions. items: required: *ref_83 type: object properties: *ref_84 examples: paginatedResults: summary: Paginated Subscription description: Example of Paginated Subscription value: &ref_474 limit: 2 count: 2 hasMore: true data: - subscriptionId: subscription 6 processingTerminalId: '1001' paymentPlan: paymentPlanId: '5' name: platinum plan link: rel: self method: GET href: https://api.payroc.com/v1/processing-terminals/1001/payment-plans/5 secureToken: secureTokenId: SecureCard1001 customerName: Joe Bloggs token: '2967533500670317' status: notValidated link: rel: self method: GET href: https://api.payroc.com/v1/processing-terminals/1001/secure-tokens/SecureCard1001 name: subscription 6 description: this is description currency: EUR setupOrder: orderId: order 201 amount: 1010 description: payment plan setup order recurringOrder: amount: 100 currentState: status: active nextDueDate: '2024-04-11' paidInvoices: 1 outstandingInvoices: 10 startDate: '2023-04-11' endDate: '2033-04-11' length: 0 type: automatic frequency: yearly pauseCollectionFor: 0 - subscriptionId: subscripion 5 processingTerminalId: '1001' paymentPlan: paymentPlanId: '1' name: gold plan link: rel: self method: GET href: https://api.payroc.com/v1/processing-terminals/1001/payment-plans/1 secureToken: secureTokenId: SecureCard1001 customerName: Joe Bloggs token: '2967533500670317' status: notValidated link: rel: self method: GET href: https://api.payroc.com/v1/processing-terminals/1001/secure-tokens/SecureCard1001 name: subscription 5 description: some description currency: EUR setupOrder: orderId: order-509 amount: 1010 recurringOrder: amount: 100 currentState: status: active nextDueDate: '2024-04-11' paidInvoices: 1 outstandingInvoices: 10 startDate: '2023-04-11' endDate: '2033-04-11' length: 0 type: automatic frequency: yearly pauseCollectionFor: 0 links: - rel: next method: get href: https://api.payroc.com/v1/processing-terminals/1001/subscriptions?limit=2&after=LN3K88F1UH - rel: previous method: get href: https://api.payroc.com/v1/processing-terminals/1001/subscriptions?limit=2&before=DBDVNUL6RG noActivity: summary: No records found description: Valid request, but no records match the criteria. value: *ref_47 '400': description: Invalid request content: *ref_14 '401': description: Identity could not be verified content: *ref_11 '403': description: Do not have permissions to perform this action content: *ref_12 '406': description: Not acceptable content: *ref_18 '500': description: An error has occured content: *ref_13 /processing-terminals/{processingTerminalId}/subscriptions/{subscriptionId}: get: tags: - Subscriptions summary: Retrieve subscription description: Retrieve a specific subscription. operationId: getSubscription parameters: - name: processingTerminalId in: path required: true description: Unique identifier that our gateway assigned to the terminal. schema: maxLength: 50 minLength: 4 type: string - name: subscriptionId in: path description: Unique identifier of the subscription that you want to view. required: true schema: maxLength: 48 minLength: 1 type: string responses: '200': description: Successful request. Returns the requested subscription. content: application/json: schema: required: *ref_83 type: object properties: *ref_84 examples: subscription: summary: Subscription description: Subscription value: *ref_85 '400': description: Invalid request content: *ref_14 '401': description: Identity could not be verified content: *ref_11 '403': description: Do not have permissions to perform this action content: *ref_12 '404': description: Resource not found content: *ref_17 '406': description: Not acceptable content: *ref_18 '500': description: An error has occured content: *ref_13 patch: tags: - Subscriptions summary: Update subscription description: | Make changes to a subscription. Structure your request to follow the RFC 6902 standard. 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 for the identifier. schema: *ref_21 example: 8e03978e-40d5-43e8-bc93-6894a57f9324 - name: processingTerminalId in: path required: true description: Unique identifier that our gateway assigned to the terminal. schema: maxLength: 50 minLength: 4 type: string - name: subscriptionId in: path description: Unique identifier of the subscription that you want to update. required: true schema: maxLength: 48 minLength: 1 type: string requestBody: content: application/json: schema: type: array description: A JSONPatch document as defined by RFC 6902 example: *ref_77 items: *ref_78 required: true responses: '200': description: Successful request. We have updated the subscription. content: application/json: schema: required: *ref_83 type: object properties: *ref_84 examples: subscription: summary: Subscription description: Subscription value: *ref_85 '400': description: Validation error content: application/problem+json: schema: type: object properties: *ref_8 required: *ref_9 examples: validationError: summary: Bad Request description: One or more validation errors occurred value: *ref_10 idempotentKeyMissing: summary: Idempotency key missing description: Idempotency key must be supplied value: *ref_23 idempotentKeyInUse: summary: Idempotency key in use description: Idempotency key in use value: *ref_26 '401': description: Identity could not be verified content: *ref_11 '403': description: Do not have permissions to perform this action content: *ref_12 '404': description: Resource not found content: *ref_17 '406': description: Not acceptable content: *ref_18 '409': description: Conflict content: *ref_79 '415': description: Unsupported media type content: *ref_80 '500': description: An error has occured content: *ref_13 /processing-terminals/{processingTerminalId}/subscriptions/{subscriptionId}/deactivate: post: tags: - Subscriptions summary: Deactivate subscription description: Deactivate a subscription. operationId: deactivateSubscription parameters: - name: processingTerminalId in: path required: true description: Unique identifier that our gateway assigned to the terminal. schema: maxLength: 50 minLength: 4 type: string - name: subscriptionId in: path description: Unique identifier of the subscription that you want to deactivate. required: true schema: maxLength: 48 minLength: 1 type: string responses: '200': description: Successful request. We deactivated the subscription. content: application/problem+json: schema: required: *ref_83 type: object properties: *ref_84 examples: deactivateSubscription: summary: Deactivate subscription description: Deactivate a subscription value: &ref_476 subscriptionId: 1001_subscription_cinema processingTerminalId: '1001' paymentPlan: paymentPlanId: 1001_paymentplan_yearly name: yearly payment plan link: rel: self method: GET href: https://api.payroc.com/v1/processing-terminals/1001/payment-plans/1001_paymentplan_yearly secureToken: secureTokenId: SecureCard1001 customerName: Joe Bloggs token: '2967533500670317' status: notValidated link: rel: self method: GET href: https://api.payroc.com/v1/processing-terminals/1001/secure-tokens/SecureCard1001 name: avant-garde description: avant-garde cinema subscription currency: EUR setupOrder: orderId: setup-order amount: 1010 description: setup order breakdown: subtotal: 1000 taxes: - name: VAT rate: 1 recurringOrder: amount: 1010 description: recurring order breakdown: subtotal: 1000 taxes: - name: VAT rate: 1 currentState: status: cancelled nextDueDate: '2023-04-25' paidInvoices: 0 outstandingInvoices: 3 startDate: '2023-04-25' endDate: '2025-04-25' length: 24 type: automatic frequency: yearly pauseCollectionFor: 0 '400': description: Invalid request content: *ref_14 '401': description: Identity could not be verified content: *ref_11 '403': description: Do not have permissions to perform this action content: *ref_12 '404': description: Resource not found content: *ref_17 '406': description: Not acceptable content: *ref_18 '409': description: Conflict content: *ref_79 '415': description: Unsupported media type content: *ref_80 '500': description: An error has occured content: *ref_13 /processing-terminals/{processingTerminalId}/subscriptions/{subscriptionId}/reactivate: post: tags: - Subscriptions summary: Re-activate subscription description: Re-activate an existing subscription. operationId: reactivateSubscription parameters: - name: processingTerminalId in: path required: true description: Unique identifier that our gateway assigned to the terminal. schema: maxLength: 50 minLength: 4 type: string - name: subscriptionId in: path description: Unique identifier of the subscription that you want to re-activate. required: true schema: maxLength: 48 minLength: 1 type: string responses: '200': description: Successful request. We re-activated the subscription. content: application/json: schema: required: *ref_83 type: object properties: *ref_84 examples: subscription: summary: Subscription description: Subscription value: *ref_85 '400': description: Invalid request content: *ref_14 '401': description: Identity could not be verified content: *ref_11 '403': description: Do not have permissions to perform this action content: *ref_12 '404': description: Resource not found content: *ref_17 '406': description: Not acceptable content: *ref_18 '409': description: Conflict content: *ref_79 '415': description: Unsupported media type content: *ref_80 '500': description: An error has occured content: *ref_13 /processing-terminals/{processingTerminalId}/subscriptions/{subscriptionId}/pay: post: tags: - Subscriptions summary: Pay manual subscription description: Process payment for a manual subscription. 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 for the identifier. schema: *ref_21 example: 8e03978e-40d5-43e8-bc93-6894a57f9324 - name: processingTerminalId in: path required: true description: Unique identifier that our gateway assigned to the terminal. schema: maxLength: 50 minLength: 4 type: string - name: subscriptionId in: path description: Unique identifier of the subscription that you want to make a payment to. required: true schema: maxLength: 48 minLength: 1 type: string requestBody: content: application/json: schema: required: &ref_295 - order properties: &ref_296 operator: maxLength: 50 minLength: 0 type: string description: Operator who initiated the request. order: description: Object that contains information about the initial cost that a customer pays to set up the subscription. type: object allOf: *ref_82 examples: subscriptionPaymentRequest: summary: Subscription manual payment description: Subscription manual payment value: &ref_477 operator: Giuseppe Green order: amount: 1010 description: manual payment breakdown: subtotal: 1000 taxes: - name: VAT rate: 1 orderId: manual payment orderx12s required: true responses: '201': description: Successful request. We have processed the payment for the subscription. content: application/json: schema: required: &ref_297 - subscriptionId - processingTerminalId - payment - secureToken - currentState type: object properties: &ref_298 subscriptionId: type: string description: Unique identifier that the merchant assigned to the subscription. processingTerminalId: type: string description: Unique identifier of the terminal that the subscription is linked to. payment: required: &ref_139 - amount - currency - dateTime - paymentId - status - responseCode - responseMessage type: object description: Object that contains information about a payment. properties: &ref_140 paymentId: maxLength: 10 minLength: 10 type: string description: Unique identifier of the payment. dateTime: type: string format: date-time description: Date and time that the payment was processed. currency: type: string description: Currency code for the payment. This code follows the ISO 4217 standard. enum: - AED - AFN - ALL - AMD - ANG - AOA - ARS - AUD - AWG - AZN - BAM - BBD - BDT - BGN - BHD - BIF - BMD - BND - BOB - BOV - BRL - BSD - BTN - BWP - BYR - BZD - CAD - CDF - CHE - CHF - CHW - CLF - CLP - CNY - COP - COU - CRC - CUC - CUP - CVE - CZK - DJF - DKK - DOP - DZD - EGP - ERN - ETB - EUR - FJD - FKP - GBP - GEL - GHS - GIP - GMD - GNF - GTQ - GYD - HKD - HNL - HRK - HTG - HUF - IDR - ILS - INR - IQD - IRR - ISK - JMD - JOD - JPY - KES - KGS - KHR - KMF - KPW - KRW - KWD - KYD - KZT - LAK - LBP - LKR - LRD - LSL - LTL - LVL - LYD - MAD - MDL - MGA - MKD - MMK - MNT - MOP - MRO - MRU - MUR - MVR - MWK - MXN - MXV - MYR - MZN - NAD - NGN - NIO - NOK - NPR - NZD - OMR - PAB - PEN - PGK - PHP - PKR - PLN - PYG - QAR - RON - RSD - RUB - RWF - SAR - SBD - SCR - SDG - SEK - SGD - SHP - SLL - SOS - SRD - SSP - STD - STN - SVC - SYP - SZL - THB - TJS - TMT - TND - TOP - TRY - TTD - TWD - TZS - UAH - UGX - USD - USN - USS - UYI - UYU - UZS - VEF - VES - VND - VUV - WST - XAF - XCD - XOF - XPF - YER - ZAR - ZMW - ZWL amount: type: integer format: int64 description: Amount of the payment. This value is in the currency’s lowest denomination, for example, cents. status: type: string description: Current status of the payment. enum: - ready - pending - declined - complete - referral - pickup - reversal - returned - admin - expired - accepted - review 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: Description of the response from the processor. link: type: object description: Object that contains information about a HATEOAS link. If we can't match a dispute to a transaction, we don't return a 'link' object. properties: *ref_3 required: *ref_4 example: *ref_5 secureToken: required: *ref_86 type: object description: Object that contains information about the secure token. properties: *ref_87 currentState: required: *ref_88 type: object properties: *ref_89 description: A snapshot of the subscription's current state. examples: subscriptionPaymentResponse: summary: Subscription manual payment description: Subscription manual payment value: &ref_478 subscriptionId: 1017_subscription_metro processingTerminalId: '1017' payment: paymentId: GTZH5WVXK9 dateTime: '2023-07-27T23:36:03.506+01:00' amount: 1010 currency: CAD status: ready responseCode: A link: rel: self method: GET href: https://api.payroc.com/v1/bank-transfer-payments/GTZH5WVXK9 secureToken: secureTokenId: MREF_465772d1-ab4e-4881-8052-5021a745ed18Df customerName: Joe Bloggs token: '2967536686508441' status: notValidated link: rel: self method: GET href: https://api.payroc.com/v1/processing-terminals/1017/secure-tokens/MREF_465772d1-ab4e-4881-8052-5021a745ed18Df currentState: status: active nextDueDate: '2024-07-01' paidInvoices: 1 outstandingInvoices: 2 headers: location: description: URI reference to created resource. style: simple explode: false schema: *ref_22 '400': description: Validation error content: application/problem+json: schema: type: object properties: *ref_8 required: *ref_9 examples: validationError: summary: Bad Request description: One or more validation errors occurred value: *ref_10 idempotentKeyMissing: summary: Idempotency key missing description: Idempotency key must be supplied value: *ref_23 idempotentKeyInUse: summary: Idempotency key in use description: Idempotency key in use value: *ref_26 '401': description: Identity could not be verified content: *ref_11 '403': description: Do not have permissions to perform this action content: *ref_12 '404': description: Resource not found content: *ref_17 '406': description: Not acceptable content: *ref_18 '409': description: Conflict content: *ref_79 '415': description: Unsupported media type content: *ref_80 '500': description: An error has occured content: *ref_13 /processing-terminals/{processingTerminalId}/secure-tokens: post: tags: - Secure tokens summary: Create secure token description: Save the customer's payment details to use in future transactions. 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 for the identifier. schema: *ref_21 example: 8e03978e-40d5-43e8-bc93-6894a57f9324 - name: processingTerminalId in: path required: true description: Unique identifier that our gateway assigned to the terminal. schema: maxLength: 50 minLength: 4 type: string requestBody: content: application/json: schema: required: &ref_329 - source type: object properties: &ref_330 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. operator: maxLength: 50 minLength: 1 type: string description: Operator who saved the customer's payment details. 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 customer: type: object description: Customer contact and address details. properties: &ref_98 firstName: maxLength: 60 minLength: 0 type: string description: Customer's first name. lastName: maxLength: 60 minLength: 0 type: string description: Customer's last name. dateOfBirth: type: string format: date description: Customer's date of birth. The format for this value is **YYYY-MM-DD**. referenceNumber: maxLength: 48 minLength: 0 type: string description: | Identifier of the transaction, also known as a customer code. For requests, you must send a value for **referenceNumber** if the customer provides one. billingAddress: required: *ref_0 type: object title: address description: Object that contains information about the address. properties: *ref_1 shippingAddress: description: Object that contains information about the customer and their shipping address. type: object properties: &ref_121 recipientName: maxLength: 50 minLength: 0 type: string description: Recipient's name. address: required: *ref_0 type: object title: address description: Object that contains information about the address. properties: *ref_1 contactMethods: uniqueItems: true description: Customer's contact information. type: array items: oneOf: *ref_2 notificationLanguage: maxLength: 2 minLength: 2 type: string format: iso-639-1 example: en description: | Language that the customer uses for notifications. This code follows the ISO 639-1 alpha-2 standard. enum: - en - fr ipAddress: required: &ref_104 - type - value type: object writeOnly: true description: Object that contains information about the IP address of the device that sent the request. properties: &ref_105 type: type: string description: Internet protocol version of the IP address. enum: - ipv4 - ipv6 value: type: string description: IP address of the merchant's POS. source: description: Object that contains information about the payment method to tokenize. type: object oneOf: - required: &ref_161 - 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_162 type: type: string description: Method that the terminal used to take the payment. enum: - ach accountType: type: string description: | Indicates the customer’s account type. **Note:** Credit card transactions don't require **accountType**. enum: - checking - savings secCode: type: string description: | Indicates the type of authorization for the transaction. - `web` – Online transaction. - `tel` – Telephone transaction. - `ccd` – Corporate credit card or debit card transaction. - `ppd` – Pre-arranged transaction. enum: - web - tel - ccd - ppd nameOnAccount: maxLength: 50 minLength: 1 type: string description: Customer's name. 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`. routingNumber: maxLength: 9 minLength: 9 pattern: ^[0-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. - required: &ref_163 - 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_164 type: type: string description: Method that the payment device used to take the payment. enum: - pad accountType: type: string description: | Indicates the customer’s account type. **Note:** Credit card transactions don't require **accountType**. enum: - checking - savings nameOnAccount: maxLength: 29 minLength: 1 type: string description: Customer's name. 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`. transitNumber: maxLength: 5 minLength: 5 pattern: ^[0-9]*$ type: string description: Five-digit code that represents the customer’s bank branch. institutionNumber: maxLength: 3 minLength: 3 pattern: ^[0-9]*$ type: string description: Three-digit code that represents the customer’s bank. - required: &ref_106 - type - cardDetails type: object writeOnly: true title: Card description: Object that contains information about the customer’s payment card. properties: &ref_107 type: type: string description: Method that the terminal used to take the payment. enum: - card accountType: type: string description: | Indicates the customer’s account type. **Note:** Credit card transactions don't require **accountType**. enum: - checking - savings cardDetails: type: object oneOf: - required: &ref_309 - entryMethod - device - rawData type: object title: Raw description: Object that contains information about the unencrypted card details. properties: &ref_310 entryMethod: type: string description: Method that the device used to capture the card details. enum: - 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 device: required: &ref_90 - model - serialNumber type: object properties: &ref_91 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 category: type: string description: Indicates if the device is attended or unattended. enum: - attended - unattended default: attended serialNumber: maxLength: 45 minLength: 1 type: string description: Serial number of the physical device. firmwareVersion: type: string description: Firmware version of the physical device. config: required: &ref_307 - quickChip type: object properties: &ref_308 quickChip: type: boolean default: false description: Indicates if Quick Chip mode is active on a merchant’s POS terminal. description: Object that contains information about the configuration of the POS terminal. description: Object that contains information about the physical device the merchant used to capture the customer’s card details. rawData: maxLength: 2147483647 minLength: 1 type: string format: hexadecimal description: Unencrypted data from the POS terminal. cardholderSignature: type: string description: Cardholder's signature in the format described in the [Special Fields and Parameters](https://worldnet.payroc.com/selfcare:api_specification:special_fields_and_parameters#the_signature_field_format) section. - required: &ref_311 - entryMethod - device - iccData type: object title: Chip description: Object that contains information about the Integrated Circuit Card (ICC). properties: &ref_312 entryMethod: type: string description: Method that the device used to capture the card details. enum: - 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 device: required: &ref_92 - model - dataKsn - serialNumber type: object description: Object that contains information about the encryption details of the POS terminal. allOf: &ref_93 - required: *ref_90 type: object properties: *ref_91 description: Object that contains information about the physical device the merchant used to capture the customer’s card details. - type: object properties: dataKsn: maxLength: 20 minLength: 20 type: string format: hexadecimal description: Key serial number. iccData: type: string format: hexadecimal description: EMV tags in Tag-Length-Value (TLV) format. firstDigitOfPan: maxLength: 1 minLength: 1 type: string description: First digit of the card number. cardholderSignature: type: string description: Cardholder’s signature. For more information about the format of the signature, see Special Fields and Parameters. - required: &ref_321 - entryMethod - keyedData type: object title: Keyed description: Object that contains information about the keyed card details. properties: &ref_322 entryMethod: type: string description: Method that the device used to capture the card details. enum: - keyed keyedData: type: object oneOf: - required: &ref_313 - dataFormat - device - encryptedData type: object title: Encrypted description: Object that contains information about the encrypted card data for keyed transactions. properties: &ref_314 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 device: required: *ref_92 type: object description: Object that contains information about the encryption details of the POS terminal. allOf: *ref_93 encryptedData: maxLength: 2147483647 minLength: 1 type: string description: Encrypted card data. format: hexadecimal firstDigitOfPan: maxLength: 1 minLength: 1 type: string description: First digit of the customer’s card number. - required: &ref_315 - 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_316 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 device: required: *ref_92 type: object description: Object that contains information about the encryption details of the POS terminal. allOf: *ref_93 encryptedPan: maxLength: 2147483647 minLength: 1 type: string format: hexadecimal description: Encrypted card number. 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, `548010*****5929`. expiryDate: pattern: '[0-9]{4}' type: string description: Expiry date of the customer’s card. cvv: pattern: '[0-9]{3,4}' type: string description: Security code of the customer’s card. 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. - required: &ref_317 - dataFormat - cardNumber type: object title: Unencrypted description: Object that contains information about the plain-text card data for keyed transactions. properties: &ref_318 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 device: required: *ref_90 type: object properties: *ref_91 description: Object that contains information about the physical device the merchant used to capture the customer’s card details. cardNumber: maxLength: 19 minLength: 12 type: string description: Customer’s card number. expiryDate: pattern: '[0-9]{4}' type: string description: | Expiry date of the customer’s card. **Note:** This field is required for most BIN lookups or electronic voucher transactions. cvv: pattern: '[0-9]{3,4}' type: string description: Security code of the customer’s card. issueNumber: pattern: '[0-9]{1,2}' type: string description: Issue number of the customer’s card. cardholderName: maxLength: 50 minLength: 1 type: string description: Cardholder’s name. cardholderSignature: type: string description: Cardholder’s signature. For more information about the format of the signature, see Special Fields and Parameters. pinDetails: type: object oneOf: - required: &ref_94 - dataFormat - pin - pinKsn type: object title: Encrypted description: Object that contains information about encrypted PIN details. properties: &ref_95 dataFormat: type: string description: Indicates the format of the PIN data. enum: - dukpt pin: maxLength: 2147483647 minLength: 1 type: string description: | Encrypted PIN. **Note:** PIN is encrypted using the DUKPT scheme. format: hexadecimal pinKsn: maxLength: 20 minLength: 20 type: string description: Key serial number. format: hexadecimal ebtDetails: required: &ref_96 - benefitCategory type: object description: Object that contains information about the Electronic Benefit Transfer (EBT) transaction. allOf: &ref_97 - required: &ref_129 - benefitCategory type: object description: Object that contains information about the Electronic Benefit Transfer (EBT) transaction. properties: &ref_130 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 withdrawal: type: boolean description: | Indicates a request to withdraw cash. **Note:** Cash withdrawal is available only for EBT Cash benefit accounts. - type: object properties: voucher: required: &ref_319 - approvalCode - serialNumber type: object properties: &ref_320 approvalCode: maxLength: 6 minLength: 6 type: string description: Authorization code that the processor issued for the transaction. serialNumber: maxLength: 15 minLength: 7 type: string description: Serial number of the voucher. description: | Object that contains information about the EBT voucher. **Note:** Voucher is available only for EBT Cash benefit accounts. - required: &ref_327 - entryMethod - swipedData type: object title: Swiped description: Object that contains information about the customer’s card details for swiped transactions. properties: &ref_328 entryMethod: type: string description: Method that the device used to capture the card details. enum: - 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 swipedData: type: object oneOf: - required: &ref_323 - dataFormat - device - encryptedData type: object title: Encrypted description: Object that contains information about the encrypted swiped card data. properties: &ref_324 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: - encrypted device: required: *ref_92 type: object description: Object that contains information about the encryption details of the POS terminal. allOf: *ref_93 encryptedData: maxLength: 2147483647 minLength: 1 type: string format: hexadecimal description: Encrypted data received from the magnetic stripe reader. firstDigitOfPan: maxLength: 1 minLength: 1 type: string description: First digit of the of the card number. fallback: type: boolean description: Indicates a technical issue with the ICC transaction that resulted in the terminal falling back to a magnetic stripe transaction. fallbackReason: type: string description: Explains the reason for the fallback. enum: - technical - repeatFallback - emptyCandidateList - required: &ref_325 - dataFormat - device - trackData type: object title: Unencrypted description: Object that contains information about plain-text swiped card data. properties: &ref_326 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 device: required: *ref_90 type: object properties: *ref_91 description: Object that contains information about the physical device the merchant used to capture the customer’s card details. trackData: maxLength: 256 minLength: 16 type: string description: Customer’s card data from the swiped transaction. fallback: type: boolean description: Indicates a technical issue with the ICC transaction that resulted in the terminal falling back to a magnetic stripe transaction. fallbackReason: type: string description: Explains the reason for the fallback. enum: - technical - repeatFallback - emptyCandidateList cardholderName: maxLength: 50 minLength: 0 type: string description: Cardholder’s name. cardholderSignature: type: string description: Cardholder’s signature. For more information about the format of the signature, see Special Fields and Parameters. pinDetails: type: object oneOf: - required: *ref_94 type: object title: Encrypted description: Object that contains information about encrypted PIN details. properties: *ref_95 ebtDetails: required: *ref_96 type: object description: Object that contains information about the Electronic Benefit Transfer (EBT) transaction. allOf: *ref_97 threeDSecure: type: object description: Object that contains information for an authentication check on the customer's payment details using the 3-D Secure protocol. oneOf: - required: &ref_110 - serviceProvider - mpiReference type: object title: Gateway description: Object that contains the 3-D Secure information from our gateway. properties: &ref_111 serviceProvider: type: string description: Provider of your 3-D Secure protocol. enum: - gateway mpiReference: maxLength: 20 minLength: 20 type: string description: Reference that our gateway assigned to the 3-D Secure authentication response. - required: &ref_112 - eci - serviceProvider type: object title: Third party description: Object that contains the 3-D Secure information from a third party. properties: &ref_113 serviceProvider: type: string description: Provider of your 3-D Secure protocol. enum: - thirdParty eci: type: string description: E-commerce indicator (ECI) is the result of the authentication check on the payment by the 3-D Secure service. enum: - fullyAuthenticated - attemptedAuthentication xid: maxLength: 50 minLength: 0 type: string description: Unique transaction identifier that the merchant assigned to the transaction and sent in the authentication request. cavv: maxLength: 50 minLength: 0 type: string description: Cardholder Authentication Value is a cryptographic value that the card issuer sends to prove an online transaction was authorized. dsTransactionId: maxLength: 36 minLength: 0 type: string description: Directory Server Transaction ID is a unique identifier that the processor assigned to the request. examples: createSecureToken: summary: Secure Token description: Secure Token value: &ref_480 operator: Adam Smith mitAgreement: unscheduled customer: firstName: Jessica lastName: Red dateOfBirth: '1990-01-01' referenceNumber: Customer-12 billingAddress: address1: Example Street address2: Example address2 address3: Example address3 city: Fresno state: California country: US postalCode: 93650 shippingAddress: recipientName: Example shipping recipientName address: address1: Example shipping street address2: Example shipping address2 address3: Exampleshipping address3 city: Austin state: Texas country: US postalCode: 73301 contactMethods: - type: email value: jessicared@mail.com notificationLanguage: en ipAddress: type: ipv4 value: 124.201.101.1 source: type: card cardDetails: entryMethod: keyed cardholderName: Joe Bloggs keyedData: dataFormat: plainText cardNumber: '4001020000000009' expiryDate: '0825' cvv: '713' 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_99 - processingTerminalId - secureTokenId - source - status - token type: object description: Object that contains information about the secure token. properties: &ref_100 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. processingTerminalId: maxLength: 50 minLength: 4 type: string description: Unique identifier that our gateway assigned to the terminal. 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 customer: type: object description: Customer contact and address details. properties: *ref_98 source: description: Object that contains information about the payment method that we tokenized. type: object oneOf: - required: &ref_299 - type - nameOnAccount - accountNumber - routingNumber type: object title: ACH account description: Object that contains the customer's account details. properties: &ref_300 type: type: string enum: - ach nameOnAccount: maxLength: 50 minLength: 1 type: string description: Customer's name. accountNumber: maxLength: 17 minLength: 4 pattern: ^[0-9]*$ type: string description: Customer's account number. routingNumber: maxLength: 9 minLength: 9 pattern: ^[0-9]*$ type: string description: Routing number of the customer's account. - required: &ref_301 - type - nameOnAccount - accountNumber - transitNumber - institutionNumber type: object title: PAD account description: Object that contains the customer's account details. properties: &ref_302 type: type: string enum: - pad nameOnAccount: maxLength: 29 minLength: 1 type: string description: Customer's name. accountNumber: maxLength: 12 minLength: 7 pattern: ^[0-9]*$ type: string description: Customer's account number. transitNumber: maxLength: 5 minLength: 5 pattern: ^[0-9]*$ type: string description: Five-digit code that represents the customer's banking branch. institutionNumber: maxLength: 3 minLength: 3 pattern: ^[0-9]*$ type: string description: Three-digit code that represents the customer's bank. - required: &ref_303 - type - cardholderName - cardNumber type: object title: Card description: Object that contains the customer's card details. properties: &ref_304 type: description: Type of payment. type: string enum: - card cardholderName: maxLength: 50 minLength: 1 type: string description: Cardholder's name. cardNumber: maxLength: 19 minLength: 12 type: string description: Primary account number of the customer's card. expiryDate: pattern: '[0-9]{4}' type: string description: Expiry date of the customer's card. 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. 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 examples: createdSecureToken: summary: Secure Token description: Secure Token value: &ref_101 secureTokenId: MREF_fce7bf52-b3b4-4270-aee9-77b938595078Hm processingTerminalId: '1001' mitAgreement: unscheduled customer: firstName: Joe lastName: Bloggs dateOfBirth: '1950-01-01' referenceNumber: Customer-1 billingAddress: address1: Example Street address2: Example address2 address3: Example address3 city: Example Town state: California country: US postalCode: '1234' shippingAddress: recipientName: Example shipping recipientName address: address1: Example shipping street address2: Example shipping address2 address3: Exampleshipping address3 city: Example shipping city state: Texas country: US postalCode: '1' contactMethods: - type: email value: joe@bloggssoftware.com notificationLanguage: en source: type: card cardholderName: Joe Bloggs cardNumber: 400102******0009 expiryDate: '0825' token: '2967532489076298' status: notValidated headers: location: description: URI reference to created resource. style: simple explode: false schema: *ref_22 '400': description: Validation error content: application/problem+json: schema: type: object properties: *ref_8 required: *ref_9 examples: validationError: summary: Bad Request description: One or more validation errors occurred value: *ref_10 idempotentKeyMissing: summary: Idempotency key missing description: Idempotency key must be supplied value: *ref_23 idempotentKeyInUse: summary: Idempotency key in use description: Idempotency key in use value: *ref_26 '401': description: Identity could not be verified content: *ref_11 '403': description: Do not have permissions to perform this action content: *ref_12 '406': description: Not acceptable content: *ref_18 '409': description: Conflict content: *ref_79 '415': description: Unsupported media type content: *ref_80 '500': description: An error has occured content: *ref_13 get: tags: - Secure tokens summary: List secure tokens description: Return a list of secure tokens that are currently saved on the terminal. operationId: listSecureTokens parameters: - name: processingTerminalId in: path description: Unique identifier that our gateway assigned to the terminal. required: true schema: maxLength: 50 minLength: 4 type: string - name: secureTokenId in: query description: Filter by the unique secure token. schema: maxLength: 200 minLength: 1 type: string - name: customerName in: query description: Filter by the customer's name. schema: maxLength: 50 minLength: 1 type: string - name: phone in: query description: Filter by the customer's phone number. schema: maxLength: 15 minLength: 1 type: string - name: email in: query description: Filter by the customer's email address. schema: maxLength: 100 minLength: 1 type: string - name: token in: query description: Filter by the token that the merchant used in a transaction to represent the customer's payment details. schema: maxLength: 19 minLength: 12 type: string - name: first6 in: query description: Filter by the first six digits of the card number. schema: pattern: '[0-9]{6}' type: string - name: last4 in: query description: Filter by the last four digits of the card or account number. schema: pattern: '[0-9]{4}' type: string - name: before in: query required: false description: Points to the resource identifier that you want to receive your results before. Typically, this is the first resource on the previous page. explode: false schema: *ref_29 example: '2571' - name: after in: query description: Points to the resource identifier that you want to receive your results after. Typically, this is the last resource on the previous page. schema: *ref_30 example: '8516' - name: limit in: query description: States the total amount of results the response is limited to. schema: *ref_31 example: 25 responses: '200': description: Successful request. Returns a list of secure tokens that are currently saved on the terminal. content: application/json: schema: required: &ref_305 - count - data - hasMore - limit type: object allOf: &ref_306 - type: object description: Contains the pagination properties that you use to navigate through a list of results. properties: *ref_32 - type: object properties: data: type: array description: Array of saved payment details. items: required: *ref_99 type: object description: Object that contains information about the secure token. properties: *ref_100 examples: paginatedResults: summary: Paginated Secure Token description: Paginated Secure Token value: &ref_479 limit: 2 count: 2 hasMore: true data: - secureTokenId: MREF_bd8abfe6-77ed-4e3b-be9f-91cb2f8801daJ2 processingTerminalId: '1001' mitAgreement: unscheduled customer: firstName: Joe lastName: Bloggs dateOfBirth: '1950-01-01' referenceNumber: Customer-1 billingAddress: address1: Example Street address2: Example address2 address3: Example address3 city: Example Town state: California country: US postalCode: '1234' shippingAddress: recipientName: Example shipping recipientName address: address1: Example shipping street address2: Example shipping address2 address3: Exampleshipping address3 city: Example shipping city state: Texas country: US postalCode: '1' source: type: card cardholderName: Joe Bloggs cardNumber: 500165******0000 expiryDate: '0825' token: '2967539621698111' status: notValidated - secureTokenId: MREF_dd8d2205-dae2-482c-b89a-2fc14513d7b7l7 processingTerminalId: '1001' mitAgreement: unscheduled customer: firstName: Joe lastName: Bloggs dateOfBirth: '1990-01-01' referenceNumber: Customer-12 billingAddress: address1: Example Street address2: Example address2 address3: Example address3 city: Example Town state: California country: US postalCode: '1234' shippingAddress: recipientName: Example shipping recipientName address: address1: Example shipping street address2: Example shipping address2 address3: Exampleshipping address3 city: Example shipping city state: Texas country: US postalCode: '1' source: type: card cardholderName: Joe Bloggs cardNumber: 400006******0006 expiryDate: '0825' token: '2967530499662487' status: notValidated links: - rel: next method: get href: https://api.payroc.com/v1/processing-terminals/1001/secure-tokens?limit=2&after=KLOLSOAKSL - rel: previous method: get href: https://api.payroc.com/v1/processing-terminals/1001/secure-tokens?limit=2&before=HUAR33GOO6 noActivity: summary: No records found description: Valid request, but no records match the criteria. value: *ref_47 '400': description: Invalid request content: *ref_14 '401': description: Identity could not be verified content: *ref_11 '403': description: Do not have permissions to perform this action content: *ref_12 '406': description: Not acceptable content: *ref_18 '500': description: An error has occured content: *ref_13 /processing-terminals/{processingTerminalId}/secure-tokens/{secureTokenId}: get: tags: - Secure tokens summary: Retrieve secure token description: Return a secure token and its related payment details. operationId: getSecureToken parameters: - name: processingTerminalId in: path description: Unique identifier that our gateway assigned to the terminal. required: true schema: maxLength: 50 minLength: 4 type: string - name: secureTokenId in: path required: true description: Unique identifier that the merchant assigned to the secure token. schema: maxLength: 200 minLength: 1 type: string responses: '200': description: Successful request. Returns the secure token and its related payment details. content: application/json: schema: required: *ref_99 type: object description: Object that contains information about the secure token. properties: *ref_100 examples: secureToken: summary: Secure Token description: Secure Token value: *ref_101 '400': description: Invalid request content: *ref_14 '401': description: Identity could not be verified content: *ref_11 '403': description: Do not have permissions to perform this action content: *ref_12 '404': description: Resource not found content: *ref_17 '406': description: Not acceptable content: *ref_18 '500': description: An error has occured content: *ref_13 patch: tags: - Secure tokens 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 standard. 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 for the identifier. schema: *ref_21 example: 8e03978e-40d5-43e8-bc93-6894a57f9324 - name: processingTerminalId in: path description: Unique identifier that our gateway assigned to the terminal. required: true schema: maxLength: 50 minLength: 4 type: string - name: secureTokenId in: path required: true description: Unique identifier that the merchant assigned to the secure token. schema: maxLength: 200 minLength: 1 type: string requestBody: content: application/json: schema: type: array description: A JSONPatch document as defined by RFC 6902 example: *ref_77 items: *ref_78 required: true responses: '200': description: Successful request. We updated the customer's payment details. content: application/json: schema: required: *ref_99 type: object description: Object that contains information about the secure token. properties: *ref_100 examples: secureToken: summary: Secure Token description: Secure Token value: *ref_101 '400': description: Validation error content: application/problem+json: schema: type: object properties: *ref_8 required: *ref_9 examples: validationError: summary: Bad Request description: One or more validation errors occurred value: *ref_10 idempotentKeyMissing: summary: Idempotency key missing description: Idempotency key must be supplied value: *ref_23 idempotentKeyInUse: summary: Idempotency key in use description: Idempotency key in use value: *ref_26 '401': description: Identity could not be verified content: *ref_11 '403': description: Do not have permissions to perform this action content: *ref_12 '404': description: Resource not found content: *ref_17 '406': description: Not acceptable content: *ref_18 '409': description: Conflict content: *ref_79 '415': description: Unsupported media type content: *ref_80 '500': description: An error has occured content: *ref_13 delete: tags: - Secure tokens summary: Delete secure token description: | Delete a secure token and its represented payment details. **Note**: If you delete a token, you can't reuse its identifier. operationId: deleteSecureToken parameters: - name: processingTerminalId in: path description: Unique identifier that our gateway assigned to the terminal. required: true schema: maxLength: 50 minLength: 4 type: string - name: secureTokenId in: path required: true description: Unique identifier that the merchant assigned to the secure token. schema: maxLength: 200 minLength: 1 type: string responses: '204': description: Successful request. We deleted the secure token. '400': description: Invalid request content: *ref_14 '401': description: Identity could not be verified content: *ref_11 '403': description: Do not have permissions to perform this action content: *ref_12 '404': description: Resource not found content: *ref_17 '500': description: An error has occured content: *ref_13 /payments: post: tags: - Payments summary: Create payment operationId: payment description: | Run a sale or pre-authorization. You can also: - Save the customer's payment details. - Set up recurring billing. - Process the transaction offline. parameters: - name: Idempotency-Key in: header required: true description: Unique identifier that you generate for each request. You must use the UUID v4 format for the identifier. schema: *ref_21 example: 8e03978e-40d5-43e8-bc93-6894a57f9324 requestBody: content: application/json: schema: required: &ref_354 - channel - order - paymentMethod - processingTerminalId type: object properties: &ref_355 channel: type: string description: Channel that the merchant used to receive the payment details. enum: - pos - web - moto 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 ran the transaction. order: required: &ref_114 - amount - currency - orderId type: object description: Object that contains information about the payment. allOf: &ref_115 - required: &ref_124 - amount - currency - orderId type: object description: Object that contains details about the transaction. properties: &ref_125 orderId: maxLength: 24 minLength: 1 type: string description: A unique identifier assigned by the merchant. 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. description: maxLength: 1024 minLength: 0 type: string description: Description of the transaction. amount: type: integer format: int64 description: Total amount of the transaction. The value is in the currency’s lowest denomination, for example, cents. currency: type: string description: Currency code for the transaction. This code follows the ISO 4217 standard. enum: - AED - AFN - ALL - AMD - ANG - AOA - ARS - AUD - AWG - AZN - BAM - BBD - BDT - BGN - BHD - BIF - BMD - BND - BOB - BOV - BRL - BSD - BTN - BWP - BYR - BZD - CAD - CDF - CHE - CHF - CHW - CLF - CLP - CNY - COP - COU - CRC - CUC - CUP - CVE - CZK - DJF - DKK - DOP - DZD - EGP - ERN - ETB - EUR - FJD - FKP - GBP - GEL - GHS - GIP - GMD - GNF - GTQ - GYD - HKD - HNL - HRK - HTG - HUF - IDR - ILS - INR - IQD - IRR - ISK - JMD - JOD - JPY - KES - KGS - KHR - KMF - KPW - KRW - KWD - KYD - KZT - LAK - LBP - LKR - LRD - LSL - LTL - LVL - LYD - MAD - MDL - MGA - MKD - MMK - MNT - MOP - MRO - MRU - MUR - MVR - MWK - MXN - MXV - MYR - MZN - NAD - NGN - NIO - NOK - NPR - NZD - OMR - PAB - PEN - PGK - PHP - PKR - PLN - PYG - QAR - RON - RSD - RUB - RWF - SAR - SBD - SCR - SDG - SEK - SGD - SHP - SLL - SOS - SRD - SSP - STD - STN - SVC - SYP - SZL - THB - TJS - TMT - TND - TOP - TRY - TTD - TWD - TZS - UAH - UGX - USD - USN - USS - UYI - UYU - UZS - VEF - VES - VND - VUV - WST - XAF - XCD - XOF - XPF - YER - ZAR - ZMW - ZWL - type: object properties: orderId: maxLength: 24 minLength: 1 type: string description: A unique identifier assigned by the merchant. 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. description: maxLength: 256 minLength: 1 type: string description: Description of the transaction. amount: type: integer format: int64 description: Total amount of the transaction. The value is in the currency’s lowest denomination, for example, cents. currency: type: string description: Currency code for the transaction. This code follows the ISO 4217 standard. enum: - AED - AFN - ALL - AMD - ANG - AOA - ARS - AUD - AWG - AZN - BAM - BBD - BDT - BGN - BHD - BIF - BMD - BND - BOB - BOV - BRL - BSD - BTN - BWP - BYR - BZD - CAD - CDF - CHE - CHF - CHW - CLF - CLP - CNY - COP - COU - CRC - CUC - CUP - CVE - CZK - DJF - DKK - DOP - DZD - EGP - ERN - ETB - EUR - FJD - FKP - GBP - GEL - GHS - GIP - GMD - GNF - GTQ - GYD - HKD - HNL - HRK - HTG - HUF - IDR - ILS - INR - IQD - IRR - ISK - JMD - JOD - JPY - KES - KGS - KHR - KMF - KPW - KRW - KWD - KYD - KZT - LAK - LBP - LKR - LRD - LSL - LTL - LVL - LYD - MAD - MDL - MGA - MKD - MMK - MNT - MOP - MRO - MRU - MUR - MVR - MWK - MXN - MXV - MYR - MZN - NAD - NGN - NIO - NOK - NPR - NZD - OMR - PAB - PEN - PGK - PHP - PKR - PLN - PYG - QAR - RON - RSD - RUB - RWF - SAR - SBD - SCR - SDG - SEK - SGD - SHP - SLL - SOS - SRD - SSP - STD - STN - SVC - SYP - SZL - THB - TJS - TMT - TND - TOP - TRY - TTD - TWD - TZS - UAH - UGX - USD - USN - USS - UYI - UYU - UZS - VEF - VES - VND - VUV - WST - XAF - XCD - XOF - XPF - YER - ZAR - ZMW - ZWL breakdown: required: &ref_122 - subtotal type: object description: Object that contains information about the breakdown of the transaction. allOf: &ref_123 - required: &ref_126 - subtotal type: object description: Object that contains information about the breakdown of the transaction. properties: &ref_127 subtotal: type: integer format: int64 description: | Total amount of the transaction before tax and fees. The value is in the currency’s lowest denomination, for example, cents. cashbackAmount: type: integer format: int64 description: Value of cashback for the transaction. tip: description: Object that contains tip information for the transaction. required: &ref_119 - type type: object properties: &ref_120 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 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 amount: minimum: 0 exclusiveMinimum: true type: integer format: int64 description: | If the value for **type** is `fixedAmount`, the value indicates the tip amount in the currency's lowest denomination, for example, cents. percentage: maximum: 100 exclusiveMaximum: false minimum: 0 exclusiveMinimum: true type: number format: double description: If the value for **type** is `percentage`, the value indicates the tip as a percentage. taxes: type: array description: List of taxes. items: required: *ref_102 type: object properties: *ref_103 surcharge: description: Object that contains surcharge information for the transaction. type: object properties: &ref_331 bypass: type: boolean description: | Indicates if the merchant wants to remove the surcharge fee from the transaction. `true` - The gateway removes the surcharge fee from the transaction. `false` - The gateway adds the fee to the transaction. amount: minimum: 0 exclusiveMinimum: true 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. percentage: maximum: 100 exclusiveMaximum: false minimum: 0 exclusiveMinimum: true type: number format: double readOnly: true description: If the merchant added a surcharge fee, this value indicates the surcharge percentage. dualPricing: description: Object that contains dual pricing information for the transaction. required: &ref_334 - offered type: object properties: &ref_335 offered: type: boolean description: Indicates if the merchant offers dual pricing to the customer. 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_332 - applied - rate - amount type: object readOnly: true properties: &ref_333 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 rate: maximum: 100 exclusiveMaximum: false minimum: 0 exclusiveMinimum: true type: number format: double description: | If the customer used a card to pay for the transaction, this value indicates the percentage that our gateway added to the transaction amount. **Note:** Our gateway returns a value for **rate** only if the value for **applied** in the request is `true`. amount: minimum: 0 exclusiveMinimum: true 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`. 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 - type: object properties: dutyAmount: type: integer format: int64 description: | Value of duties or fees for the transaction in the currency's lowest denomination, for example, cents. freightAmount: type: integer format: int64 description: | Amount for shipping in the currency's lowest denomination, for example, cents. convenienceFee: required: &ref_336 - amount type: object readOnly: true description: Object that contains convenience fee information for the transaction. properties: &ref_337 amount: minimum: 0 exclusiveMinimum: true 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. items: type: array items: description: Array of 'lineItem' objects. Each object contains information about the items in the transaction. required: &ref_338 - quantity - unitPrice type: object properties: &ref_339 commodityCode: maxLength: 45 minLength: 0 type: string description: Commodity code of the item. productCode: maxLength: 45 minLength: 0 type: string description: Product code of the item. description: maxLength: 250 minLength: 0 type: string description: Description of the item. unitOfMeasure: type: string description: Measurement for each unit of item, for example, 'GRM' (grams). enum: - ACR - AMH - AMP - APZ - ARE - ASM - ASV - ATM - ATT - BAR - BFT - BHP - BHX - BIL - BLD - BLL - BQL - BTU - BUA - BUI - BX - CCT - CDL - CEL - CEN - CGM - CKG - CLF - CLT - CMK - CMT - CNP - CNT - COU - CS - CTM - CUR - CWA - DAA - DAD - DAY - DEC - DLT - DMK - DMQ - DMT - DPC - DPT - DRA - DRI - DRL - DRM - DTH - DTN - DWT - DZN - DZP - DZR - EA - EAC - FAH - FAR - FOT - FTK - FTQ - GBQ - GFI - GGR - GII - GLD - GLI - GLL - GRM - GRN - GRO - GRT - GWH - HAR - HBA - HGM - HIU - HLT - HMQ - HMT - HPA - HTZ - HUR - INH - INK - INQ - ITM - JOU - KBA - KEL - KGM - KGS - KHZ - KJO - KMH - KMK - KMQ - KMT - KNI - KNS - KNT - KPA - KPH - KPO - KPP - KSD - KSH - KTN - KUR - KVA - KVR - KVT - KWH - KWT - LBR - LBS - LEF - LPA - LTN - LTR - LUM - LUX - MAL - MAM - MAW - MBE - MBF - MBR - MCU - MGM - MHZ - MIK - MIL - MIN - MIO - MIU - MLD - MLT - MMK - MMQ - MMT - MON - MPA - MQH - MQS - MSK - MTK - MTQ - MTR - MTS - MVA - MWH - NAR - NBB - NCL - NEW - NIU - NMB - NMI - NMP - NMR - NPL - NPT - NRL - NTT - OHM - ONZ - OZA - OZI - PAL - PCB - PCE - PGL - PK - PSC - PTD - PTI - PTL - QAN - QTD - QTI - QTL - QTR - RPM - RPS - SAN - SCO - SCR - SEC - SET - SHT - SIE - SMI - SST - ST - STI - TAH - TNE - TPR - TQD - TRL - TSD - TSH - VLT - WCD - WEB - WEE - WHR - WSD - WTT - YDK - YDQ unitPrice: minimum: 0 exclusiveMinimum: true type: number description: Price of each unit. quantity: minimum: 0 exclusiveMinimum: true type: number description: Number of units. format: double discountRate: minimum: 0 exclusiveMinimum: true type: number description: Discount rate that the merchant applies to the item. format: double taxes: type: array description: List of taxes to be applied to the item. items: required: *ref_102 type: object properties: *ref_103 dccOffer: required: &ref_133 - fxAmount - fxCurrency - fxRate - markup type: object properties: &ref_134 accepted: type: boolean writeOnly: true description: Indicates if the cardholder accepted the dynamic currency conversion (DCC) offer. offerReference: type: string description: Identifier of the DCC offer. fxAmount: type: integer format: int64 description: Amount in the cardholder’s currency in the currency’s lowest denomination, for example, cents. fxCurrency: type: string description: Three-letter currency code for the cardholder’s account. This code follows the ISO 4217 standard. enum: - AED - AFN - ALL - AMD - ANG - AOA - ARS - AUD - AWG - AZN - BAM - BBD - BDT - BGN - BHD - BIF - BMD - BND - BOB - BOV - BRL - BSD - BTN - BWP - BYR - BZD - CAD - CDF - CHE - CHF - CHW - CLF - CLP - CNY - COP - COU - CRC - CUC - CUP - CVE - CZK - DJF - DKK - DOP - DZD - EGP - ERN - ETB - EUR - FJD - FKP - GBP - GEL - GHS - GIP - GMD - GNF - GTQ - GYD - HKD - HNL - HRK - HTG - HUF - IDR - ILS - INR - IQD - IRR - ISK - JMD - JOD - JPY - KES - KGS - KHR - KMF - KPW - KRW - KWD - KYD - KZT - LAK - LBP - LKR - LRD - LSL - LTL - LVL - LYD - MAD - MDL - MGA - MKD - MMK - MNT - MOP - MRO - MRU - MUR - MVR - MWK - MXN - MXV - MYR - MZN - NAD - NGN - NIO - NOK - NPR - NZD - OMR - PAB - PEN - PGK - PHP - PKR - PLN - PYG - QAR - RON - RSD - RUB - RWF - SAR - SBD - SCR - SDG - SEK - SGD - SHP - SLL - SOS - SRD - SSP - STD - STN - SVC - SYP - SZL - THB - TJS - TMT - TND - TOP - TRY - TTD - TWD - TZS - UAH - UGX - USD - USN - USS - UYI - UYU - UZS - VEF - VES - VND - VUV - WST - XAF - XCD - XOF - XPF - YER - ZAR - ZMW - ZWL fxCurrencyCode: maxLength: 3 minLength: 3 type: string readOnly: true description: Three-digit currency code for the cardholder’s account. This code follows the ISO 4217 standard. 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 fxRate: type: number description: Foreign exchange rate for the currency. format: double markup: type: number description: Mark-up percentage rate that the DCC provider applies to the foreign exchange rate. format: double markupText: type: string readOnly: true description: Supporting text for the mark-up rate. provider: type: string readOnly: true description: Name of the DCC provider. source: type: string readOnly: true description: Source that the DCC provider uses to get the foreign exchange rates. description: Object that contains the exchange rates offer for a foreign card. standingInstructions: required: &ref_341 - processingModel - sequence type: object description: If you don't use our Subscriptions mechanism, include this section to configure your standing/recurring orders. properties: &ref_342 sequence: type: string description: Position of the transaction in the payment plan sequence. enum: - first - subsequent 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 referenceDataOfFirstTxn: description: Object that contains information about the initial payment for the payment instruction. type: object properties: &ref_340 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**. cardSchemeReferenceId: maxLength: 64 minLength: 1 type: string description: Identifier that the card brand assigns to the payment instruction. customer: type: object description: Customer contact and address details. properties: *ref_98 ipAddress: required: *ref_104 type: object writeOnly: true description: Object that contains information about the IP address of the device that sent the request. properties: *ref_105 paymentMethod: type: object description: Object that contains information about the customer's payment details. oneOf: - required: *ref_106 type: object writeOnly: true title: Card description: Object that contains information about the customer’s payment card. properties: *ref_107 - required: *ref_108 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_109 - required: &ref_157 - 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_158 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:** Credit card transactions don't require **accountType**. enum: - checking - savings serviceProvider: type: string description: Provider of the digital wallet. 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_155 - 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_156 type: type: string description: Method that the payment device used to take the payment. enum: - singleUseToken accountType: type: string description: | Indicates the customer’s account type. **Note:** Credit card transactions don't require **accountType**. enum: - checking - savings token: maxLength: 128 minLength: 128 type: string description: Unique token that the gateway assigned to the payment details. pinDetails: type: object oneOf: - required: *ref_94 type: object title: Encrypted description: Object that contains information about encrypted PIN details. properties: *ref_95 - required: &ref_350 - dataFormat - pin type: object title: Unencrypted description: Object that contains information about the unencrypted PIN details. properties: &ref_351 dataFormat: type: string description: Indicates the format of the PIN data. enum: - raw pin: maxLength: 2147483647 minLength: 1 type: string description: Customer’s unencrypted PIN. ebtDetails: required: *ref_96 type: object description: Object that contains information about the Electronic Benefit Transfer (EBT) transaction. allOf: *ref_97 threeDSecure: type: object description: Object that contains information for an authentication check on the customer's payment details using the 3-D Secure protocol. oneOf: - required: *ref_110 type: object title: Gateway description: Object that contains the 3-D Secure information from our gateway. properties: *ref_111 - required: *ref_112 type: object title: Third party description: Object that contains the 3-D Secure information from a third party. properties: *ref_113 credentialOnFile: type: object description: Object that contains information about saving the customer’s payment details. properties: &ref_128 externalVault: type: boolean default: false description: Indicates if the merchant uses a third-party vault to store the customer’s payment details. tokenize: type: boolean description: Indicates if our gateway should tokenize the customer’s payment details as part of the transaction. secureTokenId: 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. 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 offlineProcessing: required: &ref_352 - operation type: object description: Object that contains information about the transaction if the merchant ran it when the terminal was offline. properties: &ref_353 operation: type: string description: Status of the transaction. enum: - offlineDecline - offlineApproval - deferredAuthorization approvalCode: maxLength: 48 minLength: 0 type: string description: Approval code for the transaction from the processor. dateTime: type: string format: date-time description: Date and time that the merchant ran the transaction. The date follows the ISO 8601 standard. autoCapture: type: boolean default: true description: | Indicates if we should automatically capture the payment amount. - `true` - Run a sale and automatically capture the transaction. - `false`- Run a pre-authorization and capture the transaction later. **Note**: If you send `false` and the terminal doesn't support pre-authorization, we set the transaction's status to pending. The merchant must capture the transaction to take payment from the customer. processAsSale: type: boolean default: false description: | Indicates if we should immediately settle the sale transaction. The merchant cannot adjust the transaction if we immediately settle it. **Note**: If the value for **processAsSale** is `true`, the gateway ignores the value in **autoCapture**. examples: paymentRequest: summary: Payment description: Payment value: &ref_482 channel: web processingTerminalId: '1023' operator: Postman order: orderId: order123 description: Example payment currency: USD amount: 100 customer: firstName: Robert lastName: Red billingAddress: address1: billing address1 address2: billing address2 address3: billing address3 city: Los Angeles state: California country: US postalCode: 90005 shippingAddress: recipientName: shipping recipientName address: address1: shipping address1 address2: shipping address2 address3: shipping address3 city: San Diego state: California country: US postalCode: 91911 paymentMethod: type: card cardDetails: entryMethod: keyed keyedData: dataFormat: plainText device: model: paxA80 serialNumber: WPC202833004712 expiryDate: '0328' cardNumber: '5001650000000000' required: true responses: '201': description: Successful request. We processed the transaction. content: application/json: schema: required: &ref_116 - card - order - paymentId - processingTerminalId - transactionResult type: object properties: &ref_117 paymentId: maxLength: 10 minLength: 10 type: string description: Unique identifier that our gateway assigned to the transaction. processingTerminalId: maxLength: 50 minLength: 4 type: string description: Unique identifier of the terminal that initiated the transaction. operator: maxLength: 50 minLength: 0 type: string description: Operator who initiated the request. order: required: *ref_114 type: object description: Object that contains information about the payment. allOf: *ref_115 customer: type: object description: Customer contact and address details. properties: *ref_98 card: required: &ref_137 - cardNumber - entryMethod - expiryDate - type type: object properties: &ref_138 type: type: string description: Card brand that the card is linked to. For example, Visa. entryMethod: type: string description: Method that the device used to capture the card details. enum: - icc - keyed - swiped - swipedFallback - contactlessIcc - contactlessMsr cardholderName: maxLength: 50 minLength: 1 type: string description: Cardholder’s name. cardholderSignature: type: string description: Cardholder’s signature. 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. expiryDate: pattern: '[0-9]{4}' type: string description: Expiration date of the card. The format of this value is **MMYY**. secureToken: required: *ref_86 type: object description: Object that contains information about the secure token. properties: *ref_87 securityChecks: type: object properties: &ref_343 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 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 description: Object that contains information about card verification and security checks. emvTags: type: array uniqueItems: true description: Array of emvTag objects. items: required: &ref_344 - hex - value type: object description: Object that contains information about the EMV tag. properties: &ref_345 hex: type: string description: Hex code of the EMV tag. value: type: string description: Value of the EMV tag. balances: type: array description: | Array of cardBalance objects. Our gateway returns this array only when the customer uses an Electronic Benefit Transfer (EBT) card. **Note:** This field reflects the remaining balance on the card after deducting the amount of this transaction. items: required: &ref_346 - amount - benefitCategory - currency type: object properties: &ref_347 benefitCategory: type: string enum: - cash - foodStamp description: | Indicates if the balance relates to an EBT Cash account or EBT SNAP account. - `cash` – EBT Cash - `foodStamp` – EBT SNAP amount: type: integer format: int64 description: Current balance of the account. This value is in the currency's lowest denomination, for example, cents. currency: type: string description: Currency code of the account. This code follows the ISO 4217 standard. enum: - AED - AFN - ALL - AMD - ANG - AOA - ARS - AUD - AWG - AZN - BAM - BBD - BDT - BGN - BHD - BIF - BMD - BND - BOB - BOV - BRL - BSD - BTN - BWP - BYR - BZD - CAD - CDF - CHE - CHF - CHW - CLF - CLP - CNY - COP - COU - CRC - CUC - CUP - CVE - CZK - DJF - DKK - DOP - DZD - EGP - ERN - ETB - EUR - FJD - FKP - GBP - GEL - GHS - GIP - GMD - GNF - GTQ - GYD - HKD - HNL - HRK - HTG - HUF - IDR - ILS - INR - IQD - IRR - ISK - JMD - JOD - JPY - KES - KGS - KHR - KMF - KPW - KRW - KWD - KYD - KZT - LAK - LBP - LKR - LRD - LSL - LTL - LVL - LYD - MAD - MDL - MGA - MKD - MMK - MNT - MOP - MRO - MRU - MUR - MVR - MWK - MXN - MXV - MYR - MZN - NAD - NGN - NIO - NOK - NPR - NZD - OMR - PAB - PEN - PGK - PHP - PKR - PLN - PYG - QAR - RON - RSD - RUB - RWF - SAR - SBD - SCR - SDG - SEK - SGD - SHP - SLL - SOS - SRD - SSP - STD - STN - SVC - SYP - SZL - THB - TJS - TMT - TND - TOP - TRY - TTD - TWD - TZS - UAH - UGX - USD - USN - USS - UYI - UYU - UZS - VEF - VES - VND - VUV - WST - XAF - XCD - XOF - XPF - YER - ZAR - ZMW - ZWL description: Object that contains information about the total funds available in the card. description: Object that contains information about the card. refunds: type: array uniqueItems: true description: | Array of refundSummary objects. Each object contains information about refunds linked to the transaction. items: required: &ref_168 - amount - currency - dateTime - refundId - status - responseCode - responseMessage type: object description: Object that contains information about a refund. properties: &ref_169 refundId: maxLength: 10 minLength: 10 type: string description: Unique identifier of the refund. dateTime: type: string format: date-time description: Date and time that the refund was processed. currency: type: string description: Currency code for the refund. This code follows the ISO 4217 standard. enum: - AED - AFN - ALL - AMD - ANG - AOA - ARS - AUD - AWG - AZN - BAM - BBD - BDT - BGN - BHD - BIF - BMD - BND - BOB - BOV - BRL - BSD - BTN - BWP - BYR - BZD - CAD - CDF - CHE - CHF - CHW - CLF - CLP - CNY - COP - COU - CRC - CUC - CUP - CVE - CZK - DJF - DKK - DOP - DZD - EGP - ERN - ETB - EUR - FJD - FKP - GBP - GEL - GHS - GIP - GMD - GNF - GTQ - GYD - HKD - HNL - HRK - HTG - HUF - IDR - ILS - INR - IQD - IRR - ISK - JMD - JOD - JPY - KES - KGS - KHR - KMF - KPW - KRW - KWD - KYD - KZT - LAK - LBP - LKR - LRD - LSL - LTL - LVL - LYD - MAD - MDL - MGA - MKD - MMK - MNT - MOP - MRO - MRU - MUR - MVR - MWK - MXN - MXV - MYR - MZN - NAD - NGN - NIO - NOK - NPR - NZD - OMR - PAB - PEN - PGK - PHP - PKR - PLN - PYG - QAR - RON - RSD - RUB - RWF - SAR - SBD - SCR - SDG - SEK - SGD - SHP - SLL - SOS - SRD - SSP - STD - STN - SVC - SYP - SZL - THB - TJS - TMT - TND - TOP - TRY - TTD - TWD - TZS - UAH - UGX - USD - USN - USS - UYI - UYU - UZS - VEF - VES - VND - VUV - WST - XAF - XCD - XOF - XPF - YER - ZAR - ZMW - ZWL amount: type: integer format: int64 description: Amount of the refund. This value is in the currency’s lowest denomination, for example, cents. status: type: string description: Current status of the refund. enum: - ready - pending - declined - complete - referral - pickup - reversal - returned - admin - expired - accepted - review 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: Description of the response from the processor. link: type: object description: Object that contains information about a HATEOAS link. If we can't match a dispute to a transaction, we don't return a 'link' object. properties: *ref_3 required: *ref_4 example: *ref_5 supportedOperations: type: array items: &ref_141 type: string enum: - capture - refund - fullyReverse - partiallyReverse - incrementAuthorization - adjustTip - addSignature - setAsReady - setAsPending - setAsDeclined 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`. - `setAsDeclined` - Set the transaction’s status to `declined`. transactionResult: required: &ref_142 - type - status - responseCode - responseMessage type: object properties: &ref_143 type: type: string description: Transaction type. enum: - sale - refund - preAuthorization - preAuthorizationCompletion ebtType: type: string description: Sub-type for EBT transactions 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 - review 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 code for the transaction. This code follows the ISO 4217 standard. enum: - AED - AFN - ALL - AMD - ANG - AOA - ARS - AUD - AWG - AZN - BAM - BBD - BDT - BGN - BHD - BIF - BMD - BND - BOB - BOV - BRL - BSD - BTN - BWP - BYR - BZD - CAD - CDF - CHE - CHF - CHW - CLF - CLP - CNY - COP - COU - CRC - CUC - CUP - CVE - CZK - DJF - DKK - DOP - DZD - EGP - ERN - ETB - EUR - FJD - FKP - GBP - GEL - GHS - GIP - GMD - GNF - GTQ - GYD - HKD - HNL - HRK - HTG - HUF - IDR - ILS - INR - IQD - IRR - ISK - JMD - JOD - JPY - KES - KGS - KHR - KMF - KPW - KRW - KWD - KYD - KZT - LAK - LBP - LKR - LRD - LSL - LTL - LVL - LYD - MAD - MDL - MGA - MKD - MMK - MNT - MOP - MRO - MRU - MUR - MVR - MWK - MXN - MXV - MYR - MZN - NAD - NGN - NIO - NOK - NPR - NZD - OMR - PAB - PEN - PGK - PHP - PKR - PLN - PYG - QAR - RON - RSD - RUB - RWF - SAR - SBD - SCR - SDG - SEK - SGD - SHP - SLL - SOS - SRD - SSP - STD - STN - SVC - SYP - SZL - THB - TJS - TMT - TND - TOP - TRY - TTD - TWD - TZS - UAH - UGX - USD - USN - USS - UYI - UYU - UZS - VEF - VES - VND - VUV - WST - XAF - XCD - XOF - XPF - YER - ZAR - ZMW - ZWL 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: Description of the response 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. examples: createdPayment: summary: Payment description: Payment value: &ref_118 paymentId: KP77BIWR96 processingTerminalId: '1023' operator: Postman order: orderId: order123 dateTime: '2023-07-26T17:42:25.018+01:00' description: Example payment amount: 100 currency: USD customer: firstName: Robert lastName: Red billingAddress: address1: billing address address2: billing address2 address3: billing address3 city: Los Angeles state: California country: US postalCode: '90005' shippingAddress: recipientName: shipping recipientName address: address1: shipping address1 address2: shipping address2 address3: shipping address3 city: San Diego state: California country: US postalCode: '91911' card: type: MasterCard entryMethod: keyed cardNumber: 500165******0000 expiryDate: '0328' securityChecks: cvvResult: M avsResult: 'Y' supportedOperations: - capture - fullyReverse - partiallyReverse - incrementAuthorization - adjustTip - setAsPending transactionResult: type: sale status: ready approvalCode: OK3 authorizedAmount: 100 currency: USD responseCode: A responseMessage: OK3 headers: location: description: URI reference to created resource. style: simple explode: false schema: *ref_22 '400': description: Validation error content: application/problem+json: schema: type: object properties: *ref_8 required: *ref_9 examples: validationError: summary: Bad Request description: One or more validation errors occurred value: *ref_10 idempotentKeyMissing: summary: Idempotency key missing description: Idempotency key must be supplied value: *ref_23 idempotentKeyInUse: summary: Idempotency key in use description: Idempotency key in use value: *ref_26 '401': description: Identity could not be verified content: *ref_11 '403': description: Do not have permissions to perform this action content: *ref_12 '406': description: Not acceptable content: *ref_18 '409': description: Conflict content: *ref_79 '415': description: Unsupported media type content: *ref_80 '500': description: An error has occured content: *ref_13 get: tags: - Payments summary: List payments description: Return a list of payments. operationId: listPayments parameters: - name: processingTerminalId in: query description: Filter payments by terminal ID. schema: maxLength: 50 minLength: 4 type: string - name: orderId in: query description: Filter payments by order ID. schema: maxLength: 24 minLength: 1 type: string - name: operator in: query description: Filter payments by operator. schema: maxLength: 50 minLength: 1 type: string - name: cardholderName in: query description: Filter payments by the cardholder’s name. schema: maxLength: 50 minLength: 1 type: string - name: first6 in: query description: Filter payments by the first six digits of the card number that the customer used in the transaction. schema: pattern: '[0-9]{6}' type: string - name: last4 in: query description: Filter payments by the last four digits of the card number that the customer used in the transaction. schema: pattern: '[0-9]{4}' type: string - name: tender in: query description: Filter by tender type. schema: type: string enum: - ebt - creditDebit - name: tipMode in: query description: Filter payments by tip. schema: type: array items: type: string enum: - noTip - prompted - adjusted - name: type in: query description: Filter payments by transaction type. schema: type: array items: type: string enum: - sale - preAuthorization - preAuthorizationCompletion - name: status in: query description: Filter payments by the status of the transaction. schema: type: array items: type: string enum: - ready - pending - declined - complete - referral - pickup - reversal - admin - expired - accepted - review - 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: type: string format: date-time - 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: type: string format: date-time - name: settlementState in: query description: Filter payments by the settlement status of the transaction. schema: type: string enum: - settled - unsettled - name: settlementDate in: query description: Filter by payments that the processor settled on a specific date in the format **YYYY-MM-DD**. schema: type: string format: date - name: before in: query required: false description: Points to the resource identifier that you want to receive your results before. Typically, this is the first resource on the previous page. explode: false schema: *ref_29 example: '2571' - name: after in: query description: Points to the resource identifier that you want to receive your results after. Typically, this is the last resource on the previous page. schema: *ref_30 example: '8516' - name: limit in: query description: States the total amount of results the response is limited to. schema: *ref_31 example: 25 responses: '200': description: Successful request. Returns a list of payments. content: application/json: schema: required: &ref_348 - count - data - hasMore - limit type: object allOf: &ref_349 - type: object description: Contains the pagination properties that you use to navigate through a list of results. properties: *ref_32 - type: object properties: data: type: array description: Array of transactions. items: required: *ref_116 type: object properties: *ref_117 examples: paginatedResults: summary: Payment description: Payment value: &ref_481 limit: 2 count: 2 hasMore: true data: - paymentId: IFA1T74OBS processingTerminalId: '1001' operator: Automatic Payment order: orderId: '684255528917' dateTime: '2023-05-16T17:45:29+01:00' description: recurring order amount: 100 currency: EUR card: type: Visa Credit cardholderName: Joe Bloggs cardNumber: 453985******7062 expiryDate: '0129' secureToken: secureTokenId: FirefoxSecureCard1001 customerName: Joe Bloggs token: '2967533500670317' status: notValidated link: rel: self method: GET href: https://api.payroc.com/v1/processing-terminals/1001/secure-tokens/FirefoxSecureCard1001 securityChecks: cvvResult: M avsResult: X supportedOperations: - fullyReverse - setAsPending transactionResult: type: sale status: ready approvalCode: '475318' authorizedAmount: 100 currency: EUR responseCode: A responseMessage: APPROVAL - paymentId: CW4BA4MUH0 processingTerminalId: '1001' operator: Automatic Payment order: orderId: '684255528143' dateTime: '2023-05-16T17:45:28+01:00' description: yearly avant-gard cinema subscription amount: 1000 currency: EUR card: type: Visa Debit cardholderName: Joe Bloggs cardNumber: 400006******0006 expiryDate: '0129' secureToken: secureTokenId: FirefoxSecureCard1001 customerName: Joe Bloggs token: '2967533500670317' status: notValidated link: rel: self method: GET href: https://api.payroc.com/v1/processing-terminals/1001/secure-tokens/FirefoxSecureCard1001 securityChecks: cvvResult: M avsResult: X supportedOperations: - fullyReverse - setAsPending transactionResult: type: sale status: ready approvalCode: '475318' authorizedAmount: 1000 currency: EUR responseCode: A responseMessage: APPROVAL links: - rel: next method: get href: https://api.payroc.com/v1/payments?processingTerminalId=1001&limit=2&after=CW4BA4MUH0 - rel: previous method: get href: https://api.payroc.com/v1/payments?processingTerminalId=1001&limit=2&before=IFA1T74OBS noActivity: summary: No records found description: Valid request, but no records match the criteria. value: *ref_47 '400': description: Invalid request content: *ref_14 '401': description: Identity could not be verified content: *ref_11 '403': description: Do not have permissions to perform this action content: *ref_12 '406': description: Not acceptable content: *ref_18 '500': description: An error has occured content: *ref_13 /payments/{paymentId}: get: tags: - Payments summary: Retrieve payment operationId: getPayment description: Retrieve an existing payment. parameters: - name: paymentId in: path required: true description: Unique identifier of the payment that the merchant wants to retrieve. schema: maxLength: 10 minLength: 10 type: string responses: '200': description: Successful request. Returns the payment. content: application/json: schema: required: *ref_116 type: object properties: *ref_117 examples: createdPayment: summary: Payment description: Payment value: *ref_118 '400': description: Invalid request content: *ref_14 '401': description: Identity could not be verified content: *ref_11 '403': description: Do not have permissions to perform this action content: *ref_12 '404': description: Resource not found content: *ref_17 '406': description: Not acceptable content: *ref_18 '500': description: An error has occured content: *ref_13 /payments/{paymentId}/adjust: post: tags: - Payments summary: Adjust payment operationId: adjustPayment description: Adjust a transaction. parameters: - name: Idempotency-Key in: header required: true description: Unique identifier that you generate for each request. You must use the UUID v4 format for the identifier. schema: *ref_21 example: 8e03978e-40d5-43e8-bc93-6894a57f9324 - name: paymentId in: path required: true description: Unique identifier of the payment that the merchant wants to adjust. schema: maxLength: 10 minLength: 10 type: string requestBody: content: application/json: schema: required: &ref_361 - adjustments type: object description: Object that contains the transaction adjustment object. properties: &ref_362 operator: maxLength: 50 minLength: 0 type: string description: Operator who adjusted the payment. adjustments: type: array description: Array of objects that contain information about the adjustments to the payment. uniqueItems: true items: oneOf: - required: &ref_357 - 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_358 type: type: string description: Type of adjustment. enum: - order amount: minimum: 0 exclusiveMinimum: true type: integer format: int64 description: Total amount of the transaction. breakdown: type: object description: Object that contains information about the tip amount of a transaction. properties: &ref_356 tip: required: *ref_119 type: object description: Object that contains information about the tip. properties: *ref_120 - required: &ref_147 - 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_148 type: type: string description: Type of adjustment. enum: - status toStatus: type: string description: Status of the transaction. enum: - ready - pending - declined - required: &ref_149 - 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_150 type: type: string description: Type of adjustment. enum: - customer shippingAddress: description: Object that contains information about the customer and their shipping address. type: object properties: *ref_121 contactMethods: uniqueItems: true description: Customer's contact information. type: array items: oneOf: *ref_2 - required: &ref_359 - 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_360 type: type: string description: Type of adjustment. enum: - signature cardholderSignature: type: string description: Cardholder’s signature. For more information about the format of the signature, see Special Fields and Parameters. examples: adjustPaymentRequest: summary: Adjust Payment description: Adjust Payment value: &ref_483 adjustments: - type: customer shippingAddress: recipientName: new recipientName address: address1: new address1 address2: address2 address3: address3 city: Miami state: Florida country: US postalCode: 33101 - type: order amount: 1000 required: true responses: '200': description: Successful request. We adjusted the transaction. content: application/json: schema: required: *ref_116 type: object properties: *ref_117 examples: adjustPaymentResponse: summary: Adjust Payment description: Adjust Payment value: &ref_484 paymentId: HW986AQOBB processingTerminalId: '1023' order: orderId: 6u6 dateTime: '2023-07-27T10:28:44+01:00' description: Example payment amount: 1000 currency: USD customer: firstName: Robert lastName: Red billingAddress: address1: billing address address2: billing address2 address3: billing address3 city: Los Angeles state: California country: US postalCode: '90005' shippingAddress: recipientName: new recipientName address: address1: new address1 address2: address2 address3: address3 city: Miami state: Florida country: US postalCode: '33101' card: type: MasterCard entryMethod: keyed cardNumber: 500165******0000 expiryDate: '0328' securityChecks: cvvResult: M avsResult: 'Y' supportedOperations: - capture - fullyReverse - partiallyReverse - incrementAuthorization - adjustTip - setAsPending transactionResult: type: sale status: ready approvalCode: OK6 authorizedAmount: 1000 currency: USD responseCode: A responseMessage: OK6 '400': description: Validation error content: application/problem+json: schema: type: object properties: *ref_8 required: *ref_9 examples: validationError: summary: Bad Request description: One or more validation errors occurred value: *ref_10 idempotentKeyMissing: summary: Idempotency key missing description: Idempotency key must be supplied value: *ref_23 idempotentKeyInUse: summary: Idempotency key in use description: Idempotency key in use value: *ref_26 '401': description: Identity could not be verified content: *ref_11 '403': description: Do not have permissions to perform this action content: *ref_12 '404': description: Resource not found content: *ref_17 '406': description: Not acceptable content: *ref_18 '409': description: Conflict content: *ref_79 '415': description: Unsupported media type content: *ref_80 '500': description: An error has occured content: *ref_13 /payments/{paymentId}/capture: post: tags: - Payments summary: Capture payment operationId: capturePayment description: Capture an existing payment. parameters: - name: Idempotency-Key in: header required: true description: Unique identifier that you generate for each request. You must use the UUID v4 format for the identifier. schema: *ref_21 example: 8e03978e-40d5-43e8-bc93-6894a57f9324 - name: paymentId description: Unique identifier of the payment that the merchant wants to capture. in: path required: true schema: maxLength: 10 minLength: 10 type: string requestBody: content: application/json: schema: description: Object that contains the details of the payment that the merchant wants to capture. type: object properties: &ref_363 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. amount: type: integer format: int64 description: | Amount of the payment that the merchant wants to capture. The value is in the currency’s lowest denomination, for example, cents. **Note**: If the merchant does not send an amount, we capture the total amount of the transaction. breakdown: required: *ref_122 type: object description: Object that contains information about the breakdown of the transaction. allOf: *ref_123 responses: '200': description: Successful request. We captured the payment. content: application/json: schema: required: *ref_116 type: object properties: *ref_117 examples: payment: summary: Payment description: Payment value: *ref_118 '400': description: Validation error content: application/problem+json: schema: type: object properties: *ref_8 required: *ref_9 examples: validationError: summary: Bad Request description: One or more validation errors occurred value: *ref_10 idempotentKeyMissing: summary: Idempotency key missing description: Idempotency key must be supplied value: *ref_23 idempotentKeyInUse: summary: Idempotency key in use description: Idempotency key in use value: *ref_26 '401': description: Identity could not be verified content: *ref_11 '403': description: Do not have permissions to perform this action content: *ref_12 '404': description: Resource not found content: *ref_17 '406': description: Not acceptable content: *ref_18 '409': description: Conflict content: *ref_79 '415': description: Unsupported media type content: *ref_80 '500': description: An error has occured content: *ref_13 /payments/{paymentId}/reverse: post: tags: - Payments summary: Reverse payment operationId: reversePayment description: Reverse a payment. parameters: - name: Idempotency-Key in: header required: true description: Unique identifier that you generate for each request. You must use the UUID v4 format for the identifier. schema: *ref_21 example: 8e03978e-40d5-43e8-bc93-6894a57f9324 - name: paymentId description: Unique identifier of the payment that the merchant wants to reverse. in: path required: true schema: maxLength: 10 minLength: 10 type: string requestBody: content: application/json: schema: type: object properties: &ref_364 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_485 amount: 10 responses: '200': description: Successful request. We reversed the payment. content: application/json: schema: required: *ref_116 type: object properties: *ref_117 examples: reversalPayment: summary: Reversal Payment description: Reversal Payment value: &ref_486 paymentId: FRED4RL3GO processingTerminalId: '1023' order: orderId: MAPI_V2_PAY_23 dateTime: '2023-05-18T10:29:25+01:00' description: Example payment amount: 100 currency: USD customer: firstName: Giuseppe lastName: Verdi billingAddress: address1: example street address2: example address2 address3: example address3 city: example city state: California country: USA postalCode: '1' shippingAddress: recipientName: shipping recipientName address: address1: shipping address1 address2: shipping address2 address3: shipping address3 city: shipping city state: shipping state country: IT postalCode: '1' card: type: MasterCard entryMethod: keyed cardNumber: 500165******0000 expiryDate: '0328' 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 '400': description: Validation error content: application/problem+json: schema: type: object properties: *ref_8 required: *ref_9 examples: validationError: summary: Bad Request description: One or more validation errors occurred value: *ref_10 idempotentKeyMissing: summary: Idempotency key missing description: Idempotency key must be supplied value: *ref_23 idempotentKeyInUse: summary: Idempotency key in use description: Idempotency key in use value: *ref_26 '401': description: Identity could not be verified content: *ref_11 '403': description: Do not have permissions to perform this action content: *ref_12 '404': description: Resource not found content: *ref_17 '406': description: Not acceptable content: *ref_18 '409': description: Conflict content: *ref_79 '415': description: Unsupported media type content: *ref_80 '500': description: An error has occured content: *ref_13 /payments/{paymentId}/refund: post: tags: - Payments summary: Refund payment operationId: refundPayment description: Refund a payment. parameters: - name: Idempotency-Key in: header required: true description: Unique identifier that you generate for each request. You must use the UUID v4 format for the identifier. schema: *ref_21 example: 8e03978e-40d5-43e8-bc93-6894a57f9324 - name: paymentId description: Unique identifier of the payment that the merchant wants to refund. in: path required: true schema: maxLength: 10 minLength: 10 type: string requestBody: content: application/json: schema: description: Object that contains the details of the payment that the merchant wants to refund. required: &ref_365 - amount - description type: object properties: &ref_366 operator: maxLength: 50 minLength: 0 type: string description: Operator who refunded the payment. 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. description: maxLength: 100 minLength: 1 type: string description: Reason for the refund. examples: refundPaymentRequest: summary: Refund Payment description: Refund Payment value: &ref_487 amount: 100 description: refund - defective item required: true responses: '200': description: Successful request. We refunded the payment. content: application/json: schema: required: *ref_116 type: object properties: *ref_117 examples: refundPayment: summary: Refund Payment description: Refund Payment value: &ref_488 paymentId: JTWWI49L6U processingTerminalId: '1023' operator: Adam Smith order: orderId: 86f dateTime: '2024-01-16T16:57:18Z' description: Example payment amount: 100 currency: USD customer: firstName: Robert lastName: Red billingAddress: address1: billing address address2: billing address2 address3: billing address3 city: Los Angeles state: California country: US postalCode: '90005' shippingAddress: recipientName: shipping recipientName address: address1: shipping address1 address2: shipping address2 address3: shipping address3 city: San Diego state: California country: US postalCode: '91911' card: type: MasterCard entryMethod: keyed cardNumber: 500165******0000 expiryDate: '0328' securityChecks: cvvResult: M avsResult: 'Y' refunds: - refundId: BI77XQFQ05 dateTime: '2024-01-16T17:00:41Z' amount: -60 currency: USD status: ready link: rel: self method: GET href: https://api.payroc.com/v1/refunds/BI77XQFQ05 supportedOperations: - refund transactionResult: type: sale status: complete approvalCode: OK13 authorizedAmount: 100 currency: USD responseCode: A responseMessage: OK13 '400': description: Validation error content: application/problem+json: schema: type: object properties: *ref_8 required: *ref_9 examples: validationError: summary: Bad Request description: One or more validation errors occurred value: *ref_10 idempotentKeyMissing: summary: Idempotency key missing description: Idempotency key must be supplied value: *ref_23 idempotentKeyInUse: summary: Idempotency key in use description: Idempotency key in use value: *ref_26 '401': description: Identity could not be verified content: *ref_11 '403': description: Do not have permissions to perform this action content: *ref_12 '404': description: Resource not found content: *ref_17 '406': description: Not acceptable content: *ref_18 '409': description: Conflict content: *ref_79 '415': description: Unsupported media type content: *ref_80 '500': description: An error has occured content: *ref_13 /devices/{serialNumber}/payment-instructions: post: tags: - Payment instructions summary: Submit payment instruction operationId: sendPaymentInstruction description: Submit an instruction request to initiate a sale on a payment device. parameters: - name: serialNumber description: Serial number that identifies the merchant’s payment device. in: path required: true schema: maxLength: 45 minLength: 1 type: string - name: Idempotency-Key in: header required: true description: Unique identifier that you generate for each request. You must use the UUID v4 format for the identifier. schema: *ref_21 example: 8e03978e-40d5-43e8-bc93-6894a57f9324 requestBody: content: application/json: schema: required: &ref_369 - order - processingTerminalId type: object description: Object that contains the instructions for initiating a payment on a physical device. properties: &ref_370 operator: maxLength: 50 minLength: 0 type: string description: Operator who initiated the request. processingTerminalId: maxLength: 50 minLength: 4 type: string description: Unique identifier that our gateway assigned to the terminal. order: required: &ref_367 - amount - currency - orderId type: object description: Object that contains information about the payment. allOf: &ref_368 - required: *ref_124 type: object description: Object that contains details about the transaction. properties: *ref_125 - type: object properties: breakdown: required: *ref_126 type: object description: Object that contains information about the breakdown of the transaction. properties: *ref_127 customer: type: object description: Customer contact and address details. properties: *ref_98 ipAddress: required: *ref_104 type: object writeOnly: true description: Object that contains information about the IP address of the device that sent the request. properties: *ref_105 credentialOnFile: type: object description: Object that contains information about saving the customer’s payment details. properties: *ref_128 customizationOptions: type: object description: Object that contains available options to customize certain aspects of an instruction. properties: &ref_151 ebtDetails: required: *ref_129 type: object description: Object that contains information about the Electronic Benefit Transfer (EBT) transaction. properties: *ref_130 entryMethod: type: string description: | Indicates how you want the device to capture the card details. - `deviceRead` - The cardholder taps, swipes, or inserts their card. - `manualEntry` - The merchant or cardholder manually enters the card details. enum: - deviceRead - manualEntry default: 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. 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**. examples: paymentInstructionRequest: summary: Payment Instruction description: Submit an instruction for initiating a payment on a physical device. value: &ref_489 operator: jbloggs processingTerminalId: '1021' order: orderId: 4fd4-99bc currency: USD amount: 1000 customizationOptions: entryMethod: deviceRead autoCapture: true required: true responses: '202': description: Successful request. We accepted the payment instruction to process. content: application/json: schema: required: &ref_131 - paymentInstructionId - status type: object allOf: &ref_132 - type: object description: Object that contains information about the status of the instruction properties: &ref_152 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 to check the resource. - `failure` – The instruction failed. Check the error message for more information. - `inProgress` – The instruction is currently in progress. enum: - canceled - completed - failure - inProgress errorMessage: type: string description: Description of the error that caused the instruction to fail. link: type: object description: Object that contains information about a HATEOAS link. If we can't match a dispute to a transaction, we don't return a 'link' object. properties: *ref_3 required: *ref_4 example: *ref_5 - type: object properties: paymentInstructionId: maxLength: 36 minLength: 1 type: string description: Unique identifier that our gateway assigned to the instruction. examples: paymentInstruction: summary: Payment instruction description: Object that contains information about the progress of the payment instruction. value: &ref_490 paymentInstructionId: 3743a9165d134678a9100ebba3b29597 status: inProgress link: rel: self method: GET href: https://api.payroc.com/v1/payment-instructions/3743a9165d134678a9100ebba3b29597 '400': description: Validation error content: application/problem+json: schema: type: object properties: *ref_8 required: *ref_9 examples: validationError: summary: Bad Request description: One or more validation errors occurred value: *ref_10 idempotentKeyMissing: summary: Idempotency key missing description: Idempotency key must be supplied value: *ref_23 '401': description: Identity could not be verified content: *ref_11 '403': description: Do not have permissions to perform this action content: *ref_12 '404': description: Resource not found content: *ref_17 '406': description: Not acceptable content: *ref_18 '409': description: Conflict content: *ref_79 '415': description: Unsupported media type content: *ref_80 '500': description: An error has occured content: *ref_13 /payment-instructions/{paymentInstructionId}: get: tags: - Payment instructions summary: Retrieve payment instruction operationId: getPaymentInstruction description: Retrieve the current status of a specific payment instruction. parameters: - name: paymentInstructionId description: Unique identifier of the payment instruction. in: path required: true schema: maxLength: 36 minLength: 1 type: string responses: '200': description: Successful request. Returns the current status of the requested payment instruction. content: application/json: schema: required: *ref_131 type: object allOf: *ref_132 examples: paymentInstruction: summary: Payment instruction description: Object that contains information about the progress of the payment instruction. value: &ref_491 paymentInstructionId: 3743a9165d134678a9100ebba3b29597 status: completed link: rel: payment method: GET href: https://api.payroc.com/v1/payments/DD6ZDQU7L2 '400': description: Invalid request content: *ref_14 '401': description: Identity could not be verified content: *ref_11 '403': description: Do not have permissions to perform this action content: *ref_12 '404': description: Resource not found content: *ref_17 '406': description: Not acceptable content: *ref_18 '500': description: An error has occured content: *ref_13 /refunds: post: tags: - Refunds summary: Create refund operationId: unreferencedRefund description: Create an 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 for the identifier. schema: *ref_21 example: 8e03978e-40d5-43e8-bc93-6894a57f9324 requestBody: content: application/json: schema: required: &ref_373 - 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_374 channel: type: string description: Channel that the merchant used to request the refund. enum: - pos - moto 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 initiated the request. order: required: &ref_135 - amount - currency - description - orderId type: object description: Object that contains information about the refund. allOf: &ref_136 - required: *ref_124 type: object description: Object that contains details about the transaction. properties: *ref_125 - type: object properties: orderId: maxLength: 24 minLength: 1 type: string description: A unique identifier assigned by the merchant. 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. description: maxLength: 256 minLength: 1 type: string description: Description of the transaction. amount: type: integer format: int64 description: Total amount of the transaction. The value is in the currency’s lowest denomination, for example, cents. currency: type: string description: Currency code for the transaction. This code follows the ISO 4217 standard. enum: - AED - AFN - ALL - AMD - ANG - AOA - ARS - AUD - AWG - AZN - BAM - BBD - BDT - BGN - BHD - BIF - BMD - BND - BOB - BOV - BRL - BSD - BTN - BWP - BYR - BZD - CAD - CDF - CHE - CHF - CHW - CLF - CLP - CNY - COP - COU - CRC - CUC - CUP - CVE - CZK - DJF - DKK - DOP - DZD - EGP - ERN - ETB - EUR - FJD - FKP - GBP - GEL - GHS - GIP - GMD - GNF - GTQ - GYD - HKD - HNL - HRK - HTG - HUF - IDR - ILS - INR - IQD - IRR - ISK - JMD - JOD - JPY - KES - KGS - KHR - KMF - KPW - KRW - KWD - KYD - KZT - LAK - LBP - LKR - LRD - LSL - LTL - LVL - LYD - MAD - MDL - MGA - MKD - MMK - MNT - MOP - MRO - MRU - MUR - MVR - MWK - MXN - MXV - MYR - MZN - NAD - NGN - NIO - NOK - NPR - NZD - OMR - PAB - PEN - PGK - PHP - PKR - PLN - PYG - QAR - RON - RSD - RUB - RWF - SAR - SBD - SCR - SDG - SEK - SGD - SHP - SLL - SOS - SRD - SSP - STD - STN - SVC - SYP - SZL - THB - TJS - TMT - TND - TOP - TRY - TTD - TWD - TZS - UAH - UGX - USD - USN - USS - UYI - UYU - UZS - VEF - VES - VND - VUV - WST - XAF - XCD - XOF - XPF - YER - ZAR - ZMW - ZWL dccOffer: required: *ref_133 type: object properties: *ref_134 description: Object that contains the exchange rates offer for a foreign card. customer: type: object description: Customer contact and address details. properties: *ref_98 ipAddress: required: *ref_104 type: object writeOnly: true description: Object that contains information about the IP address of the device that sent the request. properties: *ref_105 refundMethod: description: Object that contains information about how the merchant refunds the customer. type: object oneOf: - required: *ref_106 type: object writeOnly: true title: Card description: Object that contains information about the customer’s payment card. properties: *ref_107 - required: *ref_108 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_109 examples: refund: summary: Refund description: Refund value: &ref_493 processingTerminalId: '1023' order: orderId: 1023_refund_oa8 description: refund example amount: 1000 currency: USD channel: web refundMethod: type: card cardDetails: entryMethod: keyed keyedData: dataFormat: plainText device: type: DATECS_BLUEPAD50 serialNumber: WPC202833004712 expiryDate: '0328' cardNumber: '5001650000000000' required: true responses: '201': description: Successful request. We processed the refund. content: application/json: schema: required: &ref_144 - card - order - processingTerminalId - refundId - transactionResult type: object description: Object that contains information about the refund. properties: &ref_145 refundId: maxLength: 10 minLength: 10 type: string description: Unique identifier that our gateway assigned to the refund. 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 requested the refund. order: required: *ref_135 type: object description: Object that contains information about the refund. allOf: *ref_136 customer: type: object description: Customer contact and address details. properties: *ref_98 card: required: *ref_137 type: object properties: *ref_138 description: Object that contains information about the card. payment: required: *ref_139 type: object description: Object that contains information about a payment. properties: *ref_140 supportedOperations: type: array items: *ref_141 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`. - `setAsDeclined` - Set the transaction’s status to `declined`. transactionResult: required: *ref_142 type: object properties: *ref_143 description: Object that contains information about the transaction response details. examples: refund: summary: Refund description: Refund value: &ref_146 refundId: CD3HN88U9F processingTerminalId: '1023' order: orderId: 1023_refund_oa8 dateTime: '2023-07-27T09:51:02.91+01:00' description: refund example amount: 1000 currency: USD card: type: MasterCard entryMethod: keyed cardNumber: 500165******0000 expiryDate: '0328' transactionResult: type: refund status: ready approvalCode: '000000' authorizedAmount: -1000 currency: USD responseCode: A responseMessage: OK5 headers: location: description: URI reference to created resource. style: simple explode: false schema: *ref_22 '400': description: Validation error content: application/problem+json: schema: type: object properties: *ref_8 required: *ref_9 examples: validationError: summary: Bad Request description: One or more validation errors occurred value: *ref_10 idempotentKeyMissing: summary: Idempotency key missing description: Idempotency key must be supplied value: *ref_23 idempotentKeyInUse: summary: Idempotency key in use description: Idempotency key in use value: *ref_26 '401': description: Identity could not be verified content: *ref_11 '403': description: Do not have permissions to perform this action content: *ref_12 '406': description: Not acceptable content: *ref_18 '409': description: Conflict content: *ref_79 '415': description: Unsupported media type content: *ref_80 '500': description: An error has occured content: *ref_13 get: tags: - Refunds summary: List refunds description: | Return a list of refunds. To filter your results, use query parameters. operationId: listRefunds parameters: - name: processingTerminalId in: query description: Filter refunds by the unique identifier that our gateway assigned to the terminal. schema: maxLength: 50 minLength: 4 type: string - name: orderId in: query description: Filter refunds by the unique identifier that the merchant assigned to the order. schema: maxLength: 24 minLength: 1 type: string - name: operator in: query description: Filter refunds by the operator who initiated the request. schema: maxLength: 50 minLength: 1 type: string - name: cardholderName in: query description: Filter refunds by cardholder name. schema: maxLength: 50 minLength: 1 type: string - name: first6 in: query description: Filter refunds by the first six digits of the card number. schema: pattern: '[0-9]{6}' type: string - name: last4 in: query description: Filter refunds by the last four digits of the card number. schema: pattern: '[0-9]{4}' type: string - name: tender in: query description: Filter by tender type. schema: type: string enum: - ebt - creditDebit - name: status in: query description: Filter refunds by the current status of the refund. schema: type: array items: type: string enum: - ready - pending - declined - complete - referral - pickup - reversal - admin - expired - accepted - review - name: dateFrom in: query description: Filter by refunds processed after a specific date. The date format follows the ISO 8601 standard. schema: type: string format: date-time - name: dateTo in: query description: Filter by refunds processed before a specific date. The date format follows the ISO 8601 standard. schema: type: string format: date-time - name: settlementState in: query description: Status of the settlement. schema: type: string enum: - settled - unsettled - name: settlementDate in: query description: Date the transaction was settled. schema: type: string format: date - name: before in: query required: false description: Points to the resource identifier that you want to receive your results before. Typically, this is the first resource on the previous page. explode: false schema: *ref_29 example: '2571' - name: after in: query description: Points to the resource identifier that you want to receive your results after. Typically, this is the last resource on the previous page. schema: *ref_30 example: '8516' - name: limit in: query description: States the total amount of results the response is limited to. schema: *ref_31 example: 25 responses: '200': description: Successful request. Returns a paginated list of refunds. content: application/json: schema: required: &ref_371 - count - data - hasMore - limit type: object description: Object that contains information about refund objects. allOf: &ref_372 - type: object description: Contains the pagination properties that you use to navigate through a list of results. properties: *ref_32 - type: object properties: data: type: array description: Array of refund objects. items: required: *ref_144 type: object description: Object that contains information about the refund. properties: *ref_145 examples: paginatedResults: summary: Paginated Refund description: Paginated Refund value: &ref_492 limit: 2 count: 2 hasMore: true data: - refundId: FPU8P48WN8 processingTerminalId: '1001' order: orderId: 1001_refund_1 dateTime: '2023-05-18T16:32:47+01:00' description: refund example amount: 1000 currency: EUR card: type: MasterCard cardNumber: 500165******0000 expiryDate: '0328' transactionResult: type: refund status: ready approvalCode: '000000' authorizedAmount: -1000 currency: EUR responseCode: A responseMessage: APPROVAL - refundId: CYGDZJF0MH processingTerminalId: '1001' order: orderId: 1001_refund dateTime: '2023-05-18T16:22:43+01:00' description: refund example amount: 1000 currency: EUR card: type: MasterCard cardNumber: 500165******0000 expiryDate: '0328' transactionResult: type: refund status: reversal approvalCode: '000000' authorizedAmount: -1000 currency: EUR responseCode: A responseMessage: APPROVAL links: - rel: next method: get href: https://api.payroc.com/v1/refunds?processingTerminalId=1001&limit=2&after=CYGDZJF0MH - rel: previous method: get href: https://api.payroc.com/v1/refunds?processingTerminalId=1001&limit=2&before=FPU8P48WN8 noActivity: summary: No records found description: Valid request, but no records match the criteria. value: *ref_47 '400': description: Invalid request content: *ref_14 '401': description: Identity could not be verified content: *ref_11 '403': description: Do not have permissions to perform this action content: *ref_12 '406': description: Not acceptable content: *ref_18 '500': description: An error has occured content: *ref_13 /refunds/{refundId}: get: tags: - Refunds summary: Retrieve refund operationId: getRefund description: Retrieve a specific refund. parameters: - name: refundId description: Unique identifier that our gateway assigned to the refund. in: path required: true schema: maxLength: 10 minLength: 10 type: string responses: '200': description: Successful request. Returns the specific refund. content: application/json: schema: required: *ref_144 type: object description: Object that contains information about the refund. properties: *ref_145 examples: refundResponse: summary: Refund description: Refund value: *ref_146 '400': description: Invalid request content: *ref_14 '401': description: Identity could not be verified content: *ref_11 '403': description: Do not have permissions to perform this action content: *ref_12 '404': description: Resource not found content: *ref_17 '406': description: Not acceptable content: *ref_18 '500': description: An error has occured content: *ref_13 /refunds/{refundId}/adjust: post: tags: - Refunds summary: Adjust refund operationId: adjustRefund description: Adjust an existing 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 for the identifier. schema: *ref_21 example: 8e03978e-40d5-43e8-bc93-6894a57f9324 - name: refundId description: Unique identifier that our gateway assigned to the refund. in: path required: true schema: maxLength: 10 minLength: 10 type: string requestBody: content: application/json: schema: required: &ref_375 - adjustments type: object description: Object that contains information about the adjustment to the refund. properties: &ref_376 operator: maxLength: 50 minLength: 0 type: string description: Operator who requested the adjustment to the refund. adjustments: type: array description: Array of objects that contain information about the adjustments to the refund. uniqueItems: true items: oneOf: - required: *ref_147 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_148 - required: *ref_149 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_150 examples: refundRequest: summary: Adjust Refund description: Adjust Refund value: &ref_494 operator: Adam Smith adjustments: - type: customer contactMethods: - type: mobile value: '+14155556666' required: true responses: '200': description: Successful request. We updated the refund. content: application/json: schema: required: *ref_144 type: object description: Object that contains information about the refund. properties: *ref_145 examples: refundResponse: summary: Adjust Refund description: Adjust Refund value: &ref_495 refundId: I2HLYTVB81 processingTerminalId: '1023' operator: Adam Smith order: orderId: 1023_refund_czz dateTime: '2023-07-28T09:44:35+01:00' description: refund example amount: 1000 currency: USD customer: contactMethods: - type: mobile value: '+14155556666' card: type: MasterCard entryMethod: keyed cardNumber: 500165******0000 expiryDate: '0328' transactionResult: type: refund status: ready approvalCode: '000000' authorizedAmount: -1000 currency: USD responseCode: A responseMessage: OK13 '400': description: Validation error content: application/problem+json: schema: type: object properties: *ref_8 required: *ref_9 examples: validationError: summary: Bad Request description: One or more validation errors occurred value: *ref_10 idempotentKeyMissing: summary: Idempotency key missing description: Idempotency key must be supplied value: *ref_23 idempotentKeyInUse: summary: Idempotency key in use description: Idempotency key in use value: *ref_26 '401': description: Identity could not be verified content: *ref_11 '403': description: Do not have permissions to perform this action content: *ref_12 '404': description: Resource not found content: *ref_17 '406': description: Not acceptable content: *ref_18 '409': description: Conflict content: *ref_79 '415': description: Unsupported media type content: *ref_80 '500': description: An error has occured content: *ref_13 /refunds/{refundId}/reverse: post: tags: - Refunds summary: Reverse refund operationId: reverseRefund description: Void an existing 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 for the identifier. schema: *ref_21 example: 8e03978e-40d5-43e8-bc93-6894a57f9324 - name: refundId description: Unique identifier that our gateway assigned to the refund. in: path required: true schema: maxLength: 10 minLength: 10 type: string responses: '200': description: Successful request. We voided the refund. content: application/json: schema: required: *ref_144 type: object description: Object that contains information about the refund. properties: *ref_145 examples: refund: summary: Reverse Refund description: Reverse Refund value: &ref_496 refundId: IH83EP2SRN processingTerminalId: '1001' order: orderId: 1001_refund_2 dateTime: '2023-05-18T16:33:10+01:00' description: refund example amount: 1000 currency: EUR card: type: Visa Credit entryMethod: keyed cardNumber: 453985******7062 expiryDate: '0328' transactionResult: type: refund status: reversal approvalCode: '000000' authorizedAmount: -1000 currency: EUR responseCode: A responseMessage: APPROVAL '400': description: Validation error content: application/problem+json: schema: type: object properties: *ref_8 required: *ref_9 examples: validationError: summary: Bad Request description: One or more validation errors occurred value: *ref_10 idempotentKeyMissing: summary: Idempotency key missing description: Idempotency key must be supplied value: *ref_23 idempotentKeyInUse: summary: Idempotency key in use description: Idempotency key in use value: *ref_26 '401': description: Identity could not be verified content: *ref_11 '403': description: Do not have permissions to perform this action content: *ref_12 '404': description: Resource not found content: *ref_17 '406': description: Not acceptable content: *ref_18 '409': description: Conflict content: *ref_79 '415': description: Unsupported media type content: *ref_80 '500': description: An error has occured content: *ref_13 /devices/{serialNumber}/refund-instructions: post: tags: - Refund instructions summary: Submit refund instruction operationId: sendRefundInstruction description: Submit an instruction request to initiate a refund on a payment device. parameters: - name: serialNumber description: Serial number that identifies the merchant’s payment device. in: path required: true schema: maxLength: 45 minLength: 1 type: string - name: Idempotency-Key in: header required: true description: Unique identifier that you generate for each request. You must use the UUID v4 format for the identifier. schema: *ref_21 example: 8e03978e-40d5-43e8-bc93-6894a57f9324 requestBody: content: application/json: schema: required: &ref_379 - order - processingTerminalId type: object description: Object that contains information about the instruction request to initiate a refund on a payment device. properties: &ref_380 operator: maxLength: 50 minLength: 0 type: string description: Operator who initiated the request. processingTerminalId: maxLength: 50 minLength: 4 type: string description: Unique identifier that our gateway assigned to the terminal. order: required: &ref_377 - amount - currency - description - orderId type: object description: Object that contains information about the refund. allOf: &ref_378 - required: *ref_124 type: object description: Object that contains details about the transaction. properties: *ref_125 - type: object customer: type: object description: Customer contact and address details. properties: *ref_98 ipAddress: required: *ref_104 type: object writeOnly: true description: Object that contains information about the IP address of the device that sent the request. properties: *ref_105 customizationOptions: type: object description: Object that contains available options to customize certain aspects of an instruction. properties: *ref_151 examples: refundInstructionRequest: summary: Refund instruction description: Submit an instruction for initiating a refund on a physical device. value: &ref_497 operator: jbloggs processingTerminalId: '1021' order: orderId: 4fd4-99bc currency: USD amount: 1000 customizationOptions: entryMethod: manualEntry required: true responses: '202': description: Successful request. We accepted the refund instruction to process. content: application/json: schema: required: &ref_153 - refundInstructionId - status type: object allOf: &ref_154 - type: object description: Object that contains information about the status of the instruction properties: *ref_152 - type: object properties: refundInstructionId: maxLength: 36 minLength: 1 type: string description: Unique identifier that our gateway assigned to the instruction. examples: refundInstruction: summary: Refund instruction description: Object that contains information about the progress of the refund instruction. value: &ref_498 refundInstructionId: 3743a9165d134678a9100ebba3b29597 status: inProgress link: rel: self method: GET href: https://api.payroc.com/v1/refund-instructions/3743a9165d134678a9100ebba3b29597 '400': description: Validation error content: application/problem+json: schema: type: object properties: *ref_8 required: *ref_9 examples: validationError: summary: Bad Request description: One or more validation errors occurred value: *ref_10 idempotentKeyMissing: summary: Idempotency key missing description: Idempotency key must be supplied value: *ref_23 '401': description: Identity could not be verified content: *ref_11 '403': description: Do not have permissions to perform this action content: *ref_12 '404': description: Resource not found content: *ref_17 '406': description: Not acceptable content: *ref_18 '409': description: Conflict content: *ref_79 '415': description: Unsupported media type content: *ref_80 '500': description: An error has occured content: *ref_13 /refund-instructions/{refundInstructionId}: get: tags: - Refund instructions summary: Retrieve refund instruction operationId: getRefundInstruction description: Retrieve the current status of a specific refund instruction. parameters: - name: refundInstructionId description: Unique identifier of the refund instruction. in: path required: true schema: maxLength: 36 minLength: 1 type: string responses: '200': description: Successful request. Returns the current status of the requested refund instruction. content: application/json: schema: required: *ref_153 type: object allOf: *ref_154 examples: refundInstruction: summary: Refund instruction description: Object that contains information about the progress of the refund instruction. value: &ref_499 refundInstructionId: 3743a9165d134678a9100ebba3b29597 status: completed link: rel: refund method: GET href: https://api.payroc.com/v1/refunds/DD6ZDQU7L2 '400': description: Invalid request content: *ref_14 '401': description: Identity could not be verified content: *ref_11 '403': description: Do not have permissions to perform this action content: *ref_12 '404': description: Resource not found content: *ref_17 '406': description: Not acceptable content: *ref_18 '500': description: An error has occured content: *ref_13 /cards/verify: post: tags: - Cards summary: Verify a card operationId: verifyCard description: Verify that a card is valid. For banks that do not support verification, we charge a micro deposit that we void immediately. parameters: - name: Idempotency-Key in: header required: true description: Unique identifier that you generate for each request. You must use the UUID v4 format for the identifier. schema: *ref_21 example: 8e03978e-40d5-43e8-bc93-6894a57f9324 requestBody: content: application/json: schema: required: &ref_381 - card - processingTerminalId type: object properties: &ref_382 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 requested to verify the card. customer: type: object description: Customer contact and address details. properties: *ref_98 card: type: object description: Object that contains information about the card. oneOf: - required: *ref_106 type: object writeOnly: true title: Card description: Object that contains information about the customer’s payment card. properties: *ref_107 examples: cardVerificationRequest: summary: Card Verification description: Card Verification value: &ref_500 operator: Mark Simpsons processingTerminalId: '1001' card: type: card cardDetails: entryMethod: keyed cardholderName: Joe Bloggs cardholderSignature: 13ab keyedData: dataFormat: plainText cardNumber: '4539858876047062' expiryDate: '1230' required: true responses: '200': description: Successful request. Returns the verification status of the card details. content: application/json: schema: required: &ref_383 - card - processingTerminalId - verified type: object properties: &ref_384 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 requested to verify the card. verified: type: boolean description: | Indicates if we have verified the card details. - `true` - The card details are valid. - `false` - The card details are not valid. dateTime: type: string format: date-time description: Date and time that we processed the request. This format follows the ISO 8601 standard, for example, 2023-03-07T15:02:07+00:00. 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”. processorResponseCode: type: string description: Response code from payment processor. This code is then mapped onto a `responseCode` enum. examples: cardVerificationResponse: summary: Card Verification description: Card Verification value: &ref_501 operator: Mark Simpsons processingTerminalId: '1001' card: type: Visa Credit entryMethod: keyed cardholderName: Joe Bloggs cardholderSignature: 13ab cardNumber: 453985******7062 expiryDate: '1230' verified: true transactionResult: status: ready responseCode: A responseMessage: APPROVAL '400': description: Validation error content: application/problem+json: schema: type: object properties: *ref_8 required: *ref_9 examples: validationError: summary: Bad Request description: One or more validation errors occurred value: *ref_10 idempotentKeyMissing: summary: Idempotency key missing description: Idempotency key must be supplied value: *ref_23 idempotentKeyInUse: summary: Idempotency key in use description: Idempotency key in use value: *ref_26 '401': description: Identity could not be verified content: *ref_11 '403': description: Do not have permissions to perform this action content: *ref_12 '404': description: Resource not found content: *ref_17 '406': description: Not acceptable content: *ref_18 '409': description: Conflict content: *ref_79 '415': description: Unsupported media type content: *ref_80 '500': description: An error has occured content: *ref_13 /cards/balance: post: tags: - Cards summary: Balance inquiry operationId: balanceCard description: Request the balance of an Electronic Benefit Transfer (EBT) card. requestBody: content: application/json: schema: required: &ref_385 - card - currency - processingTerminalId type: object properties: &ref_386 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 requested the balance inquiry. currency: type: string description: Three-letter currency code of the transaction. This format follows the ISO 4217 standard. enum: - AED - AFN - ALL - AMD - ANG - AOA - ARS - AUD - AWG - AZN - BAM - BBD - BDT - BGN - BHD - BIF - BMD - BND - BOB - BOV - BRL - BSD - BTN - BWP - BYR - BZD - CAD - CDF - CHE - CHF - CHW - CLF - CLP - CNY - COP - COU - CRC - CUC - CUP - CVE - CZK - DJF - DKK - DOP - DZD - EGP - ERN - ETB - EUR - FJD - FKP - GBP - GEL - GHS - GIP - GMD - GNF - GTQ - GYD - HKD - HNL - HRK - HTG - HUF - IDR - ILS - INR - IQD - IRR - ISK - JMD - JOD - JPY - KES - KGS - KHR - KMF - KPW - KRW - KWD - KYD - KZT - LAK - LBP - LKR - LRD - LSL - LTL - LVL - LYD - MAD - MDL - MGA - MKD - MMK - MNT - MOP - MRO - MRU - MUR - MVR - MWK - MXN - MXV - MYR - MZN - NAD - NGN - NIO - NOK - NPR - NZD - OMR - PAB - PEN - PGK - PHP - PKR - PLN - PYG - QAR - RON - RSD - RUB - RWF - SAR - SBD - SCR - SDG - SEK - SGD - SHP - SLL - SOS - SRD - SSP - STD - STN - SVC - SYP - SZL - THB - TJS - TMT - TND - TOP - TRY - TTD - TWD - TZS - UAH - UGX - USD - USN - USS - UYI - UYU - UZS - VEF - VES - VND - VUV - WST - XAF - XCD - XOF - XPF - YER - ZAR - ZMW - ZWL customer: type: object description: Customer contact and address details. properties: *ref_98 card: type: object description: Object that contains information about the card. oneOf: - required: *ref_106 type: object writeOnly: true title: Card description: Object that contains information about the customer’s payment card. properties: *ref_107 - required: *ref_155 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_156 examples: cardBalanceRequest: summary: Card Balance description: Card Balance value: &ref_502 operator: Mark Simpsons processingTerminalId: '1024' currency: USD card: type: card cardDetails: entryMethod: keyed cardholderName: Joe Bloggs cardholderSignature: 12ab keyedData: dataFormat: plainText cardNumber: '6007602801003837967' expiryDate: '1229' device: type: PAX_A920_PRO 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_387 - card - processingTerminalId type: object properties: &ref_388 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 requested the balance inquiry. card: required: *ref_137 type: object properties: *ref_138 description: Object that contains information about the card. 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”. examples: cardBalanceResponse: summary: Card Balance description: Card Balance value: &ref_503 operator: Mark Simpsons processingTerminalId: '1024' card: type: Common Benefit Identification Card entryMethod: keyed cardholderName: Joe Bloggs cardholderSignature: 12ab cardNumber: 600760*********7967 expiryDate: '1229' balances: - benefitCategory: cash amount: 10000 currency: USD responseCode: A responseMessage: Approved '400': description: Invalid request content: *ref_14 '401': description: Identity could not be verified content: *ref_11 '403': description: Do not have permissions to perform this action content: *ref_12 '404': description: Resource not found content: *ref_17 '406': description: Not acceptable content: *ref_18 '409': description: Conflict content: *ref_79 '415': description: Unsupported media type content: *ref_80 '500': description: An error has occured content: *ref_13 /cards/bin-lookup: post: tags: - Cards summary: Lookup BIN information description: Perform a BIN (Bank Identification Number) lookup to retrieve information about a card. operationId: binLookup requestBody: content: application/json: schema: required: &ref_391 - card type: object properties: &ref_392 processingTerminalId: maxLength: 50 minLength: 4 type: string description: The terminal number assigned by the gateway. amount: minimum: 0 exclusiveMinimum: true type: integer format: int64 description: | The amount in the currency's lowest denomination. If the card is eligible for surcharging, sending this field will allow the gateway to calculate and return the surcharge amount. currency: type: string description: | The currency of the transaction. A 3-letter code as per the [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217#Active_codes) standard. enum: - AED - AFN - ALL - AMD - ANG - AOA - ARS - AUD - AWG - AZN - BAM - BBD - BDT - BGN - BHD - BIF - BMD - BND - BOB - BOV - BRL - BSD - BTN - BWP - BYR - BZD - CAD - CDF - CHE - CHF - CHW - CLF - CLP - CNY - COP - COU - CRC - CUC - CUP - CVE - CZK - DJF - DKK - DOP - DZD - EGP - ERN - ETB - EUR - FJD - FKP - GBP - GEL - GHS - GIP - GMD - GNF - GTQ - GYD - HKD - HNL - HRK - HTG - HUF - IDR - ILS - INR - IQD - IRR - ISK - JMD - JOD - JPY - KES - KGS - KHR - KMF - KPW - KRW - KWD - KYD - KZT - LAK - LBP - LKR - LRD - LSL - LTL - LVL - LYD - MAD - MDL - MGA - MKD - MMK - MNT - MOP - MRO - MRU - MUR - MVR - MWK - MXN - MXV - MYR - MZN - NAD - NGN - NIO - NOK - NPR - NZD - OMR - PAB - PEN - PGK - PHP - PKR - PLN - PYG - QAR - RON - RSD - RUB - RWF - SAR - SBD - SCR - SDG - SEK - SGD - SHP - SLL - SOS - SRD - SSP - STD - STN - SVC - SYP - SZL - THB - TJS - TMT - TND - TOP - TRY - TTD - TWD - TZS - UAH - UGX - USD - USN - USS - UYI - UYU - UZS - VEF - VES - VND - VUV - WST - XAF - XCD - XOF - XPF - YER - ZAR - ZMW - ZWL card: type: object description: Object that contains information about the card. oneOf: - required: *ref_106 type: object writeOnly: true title: Card description: Object that contains information about the customer’s payment card. properties: *ref_107 - required: &ref_389 - type - bin type: object writeOnly: true title: Card BIN description: Object that contains information about the card's bank identification number (BIN). properties: &ref_390 type: type: string description: Method that the terminal used to take the payment. enum: - cardBin bin: maxLength: 12 minLength: 6 type: string - required: *ref_108 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_109 - required: *ref_157 type: object writeOnly: true title: Digital wallet description: Object that contains information about the payment details in the customer’s digital wallet. properties: *ref_158 examples: binLookupRequest: summary: BIN lookup description: BIN lookup value: &ref_504 operator: Andrew White processingTerminalId: '1005' card: type: card cardDetails: entryMethod: keyed cardholderName: Joe Bloggs cardholderSignature: 13ab keyedData: dataFormat: plainText cardNumber: '5001650000000000' expiryDate: '1225' required: true responses: '200': description: Successful request. Returns the BIN information. content: application/json: schema: required: &ref_159 - type - cardNumber type: object readOnly: true properties: &ref_160 type: type: string description: Card brand, 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. currency: type: string description: Code that represents the currency of the card. enum: - AED - AFN - ALL - AMD - ANG - AOA - ARS - AUD - AWG - AZN - BAM - BBD - BDT - BGN - BHD - BIF - BMD - BND - BOB - BOV - BRL - BSD - BTN - BWP - BYR - BZD - CAD - CDF - CHE - CHF - CHW - CLF - CLP - CNY - COP - COU - CRC - CUC - CUP - CVE - CZK - DJF - DKK - DOP - DZD - EGP - ERN - ETB - EUR - FJD - FKP - GBP - GEL - GHS - GIP - GMD - GNF - GTQ - GYD - HKD - HNL - HRK - HTG - HUF - IDR - ILS - INR - IQD - IRR - ISK - JMD - JOD - JPY - KES - KGS - KHR - KMF - KPW - KRW - KWD - KYD - KZT - LAK - LBP - LKR - LRD - LSL - LTL - LVL - LYD - MAD - MDL - MGA - MKD - MMK - MNT - MOP - MRO - MRU - MUR - MVR - MWK - MXN - MXV - MYR - MZN - NAD - NGN - NIO - NOK - NPR - NZD - OMR - PAB - PEN - PGK - PHP - PKR - PLN - PYG - QAR - RON - RSD - RUB - RWF - SAR - SBD - SCR - SDG - SEK - SGD - SHP - SLL - SOS - SRD - SSP - STD - STN - SVC - SYP - SZL - THB - TJS - TMT - TND - TOP - TRY - TTD - TWD - TZS - UAH - UGX - USD - USN - USS - UYI - UYU - UZS - VEF - VES - VND - VUV - WST - XAF - XCD - XOF - XPF - YER - ZAR - ZMW - ZWL debit: type: boolean description: Indicates if the card is a debit card. surcharging: required: &ref_393 - allowed type: object properties: &ref_394 allowed: type: boolean description: Indicates if the merchant can add a surcharge when the customer uses this card. amount: minimum: 0 exclusiveMinimum: true type: integer format: int64 description: | Surcharge amount to add to the transaction. **Note:** Our gateway returns **amount** only if the request contained an example transaction amount. percentage: maximum: 100 exclusiveMaximum: false minimum: 0 exclusiveMinimum: true type: number format: double description: Surcharge rate that the merchant configures on their account. disclosure: type: string description: Statement used to disclose the surcharge fee to the customer. description: Object that contains surcharge information. Our gateway returns this object only if the merchant adds a surcharge to transactions. description: Object that contains information about the card. examples: binLookupResponse: summary: BIN lookup description: BIN lookup value: &ref_505 type: MASTERCARD cardNumber: 500165******0000 country: US currency: USD debit: false '400': description: Invalid request content: *ref_14 '401': description: Identity could not be verified content: *ref_11 '403': description: Do not have permissions to perform this action content: *ref_12 '404': description: Resource not found content: *ref_17 '406': description: Not acceptable content: *ref_18 '409': description: Conflict content: *ref_79 '415': description: Unsupported media type content: *ref_80 '500': description: An error has occured content: *ref_13 /fx-rates: post: tags: - Currency conversion summary: Fx rates inquiry description: | Check if a customer’s card is eligible for Dynamic Currency Conversion (DCC). If the card is eligible for DCC, offer currency conversion to the customer during a transaction. **Note:** We offer this through the DCC service, which gives customers a choice to pay in the local currency or their own currency. operationId: getFxRates requestBody: content: application/json: schema: required: &ref_395 - baseAmount - baseCurrency - channel - paymentMethod - processingTerminalId type: object properties: &ref_396 channel: description: Channel that the merchant used to receive payment details for the transaction. type: string enum: - pos - web - moto processingTerminalId: maxLength: 50 minLength: 4 type: string description: Unique identifier that our gateway assigned to the terminal. operator: maxLength: 50 minLength: 1 type: string description: Operator who ran the transaction. baseAmount: minimum: 0 exclusiveMinimum: true 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: Code that represents the local currency. enum: - AED - AFN - ALL - AMD - ANG - AOA - ARS - AUD - AWG - AZN - BAM - BBD - BDT - BGN - BHD - BIF - BMD - BND - BOB - BOV - BRL - BSD - BTN - BWP - BYR - BZD - CAD - CDF - CHE - CHF - CHW - CLF - CLP - CNY - COP - COU - CRC - CUC - CUP - CVE - CZK - DJF - DKK - DOP - DZD - EGP - ERN - ETB - EUR - FJD - FKP - GBP - GEL - GHS - GIP - GMD - GNF - GTQ - GYD - HKD - HNL - HRK - HTG - HUF - IDR - ILS - INR - IQD - IRR - ISK - JMD - JOD - JPY - KES - KGS - KHR - KMF - KPW - KRW - KWD - KYD - KZT - LAK - LBP - LKR - LRD - LSL - LTL - LVL - LYD - MAD - MDL - MGA - MKD - MMK - MNT - MOP - MRO - MRU - MUR - MVR - MWK - MXN - MXV - MYR - MZN - NAD - NGN - NIO - NOK - NPR - NZD - OMR - PAB - PEN - PGK - PHP - PKR - PLN - PYG - QAR - RON - RSD - RUB - RWF - SAR - SBD - SCR - SDG - SEK - SGD - SHP - SLL - SOS - SRD - SSP - STD - STN - SVC - SYP - SZL - THB - TJS - TMT - TND - TOP - TRY - TTD - TWD - TZS - UAH - UGX - USD - USN - USS - UYI - UYU - UZS - VEF - VES - VND - VUV - WST - XAF - XCD - XOF - XPF - YER - ZAR - ZMW - ZWL paymentMethod: type: object description: Object that contains information about the customer's payment details. oneOf: - required: *ref_106 type: object writeOnly: true title: Card description: Object that contains information about the customer’s payment card. properties: *ref_107 - required: *ref_108 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_109 - required: *ref_157 type: object writeOnly: true title: Digital wallet description: Object that contains information about the payment details in the customer’s digital wallet. properties: *ref_158 examples: fxRateRequest: summary: Fx-Rate description: Fx-Rate value: &ref_506 channel: web operator: Aaron processingTerminalId: '1005' baseAmount: 10000 baseCurrency: EUR paymentMethod: type: card accountType: checking cardDetails: entryMethod: keyed cardholderName: Joe Bloggs keyedData: dataFormat: plainText cardNumber: '5001650000000000' expiryDate: '0430' required: true responses: '200': description: Successful request. Returns the currency conversion rate for the transaction. content: application/json: schema: required: &ref_399 - baseAmount - baseCurrency - cardInfo - inquiryResult - processingTerminalId type: object description: Foreign exchange rate for the transaction. properties: &ref_400 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 ran the transaction. baseAmount: minimum: 0 exclusiveMinimum: true 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: Code that represents the local currency. enum: - AED - AFN - ALL - AMD - ANG - AOA - ARS - AUD - AWG - AZN - BAM - BBD - BDT - BGN - BHD - BIF - BMD - BND - BOB - BOV - BRL - BSD - BTN - BWP - BYR - BZD - CAD - CDF - CHE - CHF - CHW - CLF - CLP - CNY - COP - COU - CRC - CUC - CUP - CVE - CZK - DJF - DKK - DOP - DZD - EGP - ERN - ETB - EUR - FJD - FKP - GBP - GEL - GHS - GIP - GMD - GNF - GTQ - GYD - HKD - HNL - HRK - HTG - HUF - IDR - ILS - INR - IQD - IRR - ISK - JMD - JOD - JPY - KES - KGS - KHR - KMF - KPW - KRW - KWD - KYD - KZT - LAK - LBP - LKR - LRD - LSL - LTL - LVL - LYD - MAD - MDL - MGA - MKD - MMK - MNT - MOP - MRO - MRU - MUR - MVR - MWK - MXN - MXV - MYR - MZN - NAD - NGN - NIO - NOK - NPR - NZD - OMR - PAB - PEN - PGK - PHP - PKR - PLN - PYG - QAR - RON - RSD - RUB - RWF - SAR - SBD - SCR - SDG - SEK - SGD - SHP - SLL - SOS - SRD - SSP - STD - STN - SVC - SYP - SZL - THB - TJS - TMT - TND - TOP - TRY - TTD - TWD - TZS - UAH - UGX - USD - USN - USS - UYI - UYU - UZS - VEF - VES - VND - VUV - WST - XAF - XCD - XOF - XPF - YER - ZAR - ZMW - ZWL inquiryResult: required: &ref_397 - dccOffered type: object properties: &ref_398 dccOffered: type: boolean default: false description: Indicates if the card is eligible for DCC. causeOfRejection: type: string description: Explains why the DCC service did not offer a currency conversion rate to the customer. description: Object that contains information about the currency conversion rate. dccOffer: required: *ref_133 type: object properties: *ref_134 description: Object that contains the exchange rates offer for a foreign card. cardInfo: required: *ref_159 type: object readOnly: true properties: *ref_160 description: Object that contains information about the card. examples: fxRateResponse: summary: Fx-Rate description: Fx-Rate value: &ref_507 processingTerminalId: '1005' operator: Aaron baseAmount: 10000 baseCurrency: EUR inquiryResult: dccOffered: true dccOffer: accepted: true reference: 3396977e-40b9-4b26-8a3f-c25bc1280ee2 fxAmount: 13612 fxCurrency: JPY fxCurrencyCode: '392' fxCurrencyExponent: 0 fxRate: 136.1248 markup: 3 provider: FEXCO source: REUTERS WHOLESALE INTERBANK cardInfo: type: MASTERCARD cardNumber: 500165******0000 '400': description: Invalid request content: *ref_14 '401': description: Identity could not be verified content: *ref_11 '403': description: Do not have permissions to perform this action content: *ref_12 '404': description: Resource not found content: *ref_17 '406': description: Not acceptable content: *ref_18 '409': description: Conflict content: *ref_79 '415': description: Unsupported media type content: *ref_80 '500': description: An error has occured content: *ref_13 /bank-transfer-payments: post: tags: - Bank transfer payments summary: Create payment operationId: bankTransferPayment description: Run a sale with a customer's bank account details. parameters: - name: Idempotency-Key in: header required: true description: Unique identifier that you generate for each request. You must use the UUID v4 format for the identifier. schema: *ref_21 example: 8e03978e-40d5-43e8-bc93-6894a57f9324 requestBody: content: application/json: schema: required: &ref_407 - order - paymentMethod - processingTerminalId type: object description: Object that contains information about the sale and the customer's bank details. properties: &ref_408 processingTerminalId: maxLength: 50 minLength: 4 type: string description: Unique identifier that our gateway assigned to the terminal. order: required: &ref_165 - amount - currency - orderId type: object allOf: &ref_166 - required: *ref_124 type: object description: Object that contains details about the transaction. properties: *ref_125 - type: object properties: orderId: maxLength: 24 minLength: 1 type: string description: A unique identifier assigned by the merchant. 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. description: maxLength: 256 minLength: 1 type: string description: A brief description of the transaction. amount: type: integer format: int64 description: The total amount in the currency's lowest denomination. For example, cents. currency: type: string description: | The currency of the transaction. A 3-letter code as per the [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217#Active_codes) standard. enum: - AED - AFN - ALL - AMD - ANG - AOA - ARS - AUD - AWG - AZN - BAM - BBD - BDT - BGN - BHD - BIF - BMD - BND - BOB - BOV - BRL - BSD - BTN - BWP - BYR - BZD - CAD - CDF - CHE - CHF - CHW - CLF - CLP - CNY - COP - COU - CRC - CUC - CUP - CVE - CZK - DJF - DKK - DOP - DZD - EGP - ERN - ETB - EUR - FJD - FKP - GBP - GEL - GHS - GIP - GMD - GNF - GTQ - GYD - HKD - HNL - HRK - HTG - HUF - IDR - ILS - INR - IQD - IRR - ISK - JMD - JOD - JPY - KES - KGS - KHR - KMF - KPW - KRW - KWD - KYD - KZT - LAK - LBP - LKR - LRD - LSL - LTL - LVL - LYD - MAD - MDL - MGA - MKD - MMK - MNT - MOP - MRO - MRU - MUR - MVR - MWK - MXN - MXV - MYR - MZN - NAD - NGN - NIO - NOK - NPR - NZD - OMR - PAB - PEN - PGK - PHP - PKR - PLN - PYG - QAR - RON - RSD - RUB - RWF - SAR - SBD - SCR - SDG - SEK - SGD - SHP - SLL - SOS - SRD - SSP - STD - STN - SVC - SYP - SZL - THB - TJS - TMT - TND - TOP - TRY - TTD - TWD - TZS - UAH - UGX - USD - USN - USS - UYI - UYU - UZS - VEF - VES - VND - VUV - WST - XAF - XCD - XOF - XPF - YER - ZAR - ZMW - ZWL breakdown: required: &ref_401 - subtotal type: object description: Object that contains information about the taxes and tip amount on the transaction. properties: &ref_402 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. tip: description: Object that contains tip information for the transaction. required: *ref_119 type: object properties: *ref_120 taxes: type: array description: Array of tax objects. items: required: *ref_102 type: object properties: *ref_103 description: Object that contains information about the transaction. customer: type: object properties: &ref_167 notificationLanguage: maxLength: 2 minLength: 2 type: string format: iso-639-1 example: en description: Customer's preferred notification language. This code follows the ISO 639-1 standard. enum: - en - fr contactMethods: uniqueItems: true description: Customer's contact information. type: array items: oneOf: *ref_2 description: Object that contains information about the customer. credentialOnFile: type: object description: Object that contains information about saving the customer’s payment details. properties: *ref_128 paymentMethod: type: object description: Object that contains information about the customer's payment details. oneOf: - required: *ref_161 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_162 - required: *ref_163 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_164 - required: *ref_108 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_109 examples: createdBankTransferPaymentStoreToken: summary: Store Token Bank Transfer Payment description: Bank Transfer Payment with ACH payload and token storage value: &ref_509 processingTerminalId: '1017' order: orderId: orderpop123 description: sample order amount: 11110 currency: USD breakdown: subtotal: 10000 tip: type: percentage percentage: 10 taxes: - name: VAT rate: 1 customer: notificationLanguage: en contactMethods: - type: email value: joe@blogssoftware.com credentialOnFile: tokenize: true paymentMethod: type: ach accountType: checking nameOnAccount: Joe Bloggs accountNumber: '11101010' routingNumber: '053200983' secCode: web required: true responses: '201': description: Successful request. We processed the sale. content: application/json: schema: required: &ref_170 - bankAccount - order - paymentId - processingTerminalId - transactionResult type: object description: Object that contains information about the sale and the customer's bank details. properties: &ref_171 paymentId: maxLength: 10 minLength: 10 type: string description: Unique identifier that our gateway assigned to the payment. processingTerminalId: maxLength: 50 minLength: 4 type: string description: Unique identifier that our gateway assigned to the terminal. order: required: *ref_165 type: object allOf: *ref_166 description: Object that contains information about the transaction. customer: type: object properties: *ref_167 description: Object that contains information about the customer. bankAccount: description: Object that contains information about the bank account. type: object oneOf: - required: &ref_175 - accountNumber - nameOnAccount - routingNumber - type type: object title: ACH account description: Object that contains the customer's account details. properties: &ref_176 type: type: string enum: - ach secCode: type: string description: | SEC code for the transaction. - `web` - Online transaction. - `tel` - Telephone transaction. - `ccd` - Corporate credit or debit transaction. - `ppd` - Pre-arranged transaction. enum: - web - tel - ccd - ppd nameOnAccount: maxLength: 50 minLength: 1 type: string description: Customer's name. accountNumber: maxLength: 17 minLength: 4 type: string description: Customer's bank account number. We mask all digits except the last four digits. 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. secureToken: required: *ref_86 type: object description: Object that contains information about the secure token. properties: *ref_87 - required: &ref_177 - accountNumber - institutionNumber - nameOnAccount - transitNumber - type type: object title: PAD account description: Object that contains the customer's account details. properties: &ref_178 type: type: string enum: - pad nameOnAccount: maxLength: 29 minLength: 1 type: string description: Customer's name. accountNumber: maxLength: 12 minLength: 7 type: string description: Customer's bank account number. We mask all digits except the last four digits. transitNumber: maxLength: 5 minLength: 5 type: string description: Five-digit code that represents the customer's banking branch. institutionNumber: maxLength: 3 minLength: 3 type: string description: Three-digit code that represents the customer's bank. secureToken: required: *ref_86 type: object description: Object that contains information about the secure token. properties: *ref_87 refunds: type: array uniqueItems: true description: List of refunds issued against the payment items: required: *ref_168 type: object description: Object that contains information about a refund. properties: *ref_169 returns: type: array uniqueItems: true description: List of returns issued against the payment items: required: &ref_403 - date - paymentId - represented - returnCode - returnReason type: object description: Object that contains information about a return. properties: &ref_404 paymentId: maxLength: 10 minLength: 10 type: string description: Unique identifier that our gateway assigned to the payment. date: type: string format: date description: The date that the check was returned. returnCode: type: string description: The NACHA return code. returnReason: type: string description: The reason why the check was returned. represented: type: boolean description: Indicates whether the return has been re-presented. link: type: object description: Object that contains information about a HATEOAS link. If we can't match a dispute to a transaction, we don't return a 'link' object. properties: *ref_3 required: *ref_4 example: *ref_5 representment: required: *ref_139 type: object description: Object that contains information about a payment. properties: *ref_140 transactionResult: required: &ref_179 - responseMessage - status - type type: object readOnly: true properties: &ref_180 type: type: string description: Type of transaction. enum: - payment - refund - unreferencedRefund - accountVerification status: type: string description: Status of the transaction. enum: - ready - pending - declined - complete - admin - reversal - returned authorizedAmount: type: number description: | Amount of the transaction. **Note:** The amount is negative for a refund. currency: type: string description: Currency code of the transaction. This code follows the ISO 4217 standard. enum: - AED - AFN - ALL - AMD - ANG - AOA - ARS - AUD - AWG - AZN - BAM - BBD - BDT - BGN - BHD - BIF - BMD - BND - BOB - BOV - BRL - BSD - BTN - BWP - BYR - BZD - CAD - CDF - CHE - CHF - CHW - CLF - CLP - CNY - COP - COU - CRC - CUC - CUP - CVE - CZK - DJF - DKK - DOP - DZD - EGP - ERN - ETB - EUR - FJD - FKP - GBP - GEL - GHS - GIP - GMD - GNF - GTQ - GYD - HKD - HNL - HRK - HTG - HUF - IDR - ILS - INR - IQD - IRR - ISK - JMD - JOD - JPY - KES - KGS - KHR - KMF - KPW - KRW - KWD - KYD - KZT - LAK - LBP - LKR - LRD - LSL - LTL - LVL - LYD - MAD - MDL - MGA - MKD - MMK - MNT - MOP - MRO - MRU - MUR - MVR - MWK - MXN - MXV - MYR - MZN - NAD - NGN - NIO - NOK - NPR - NZD - OMR - PAB - PEN - PGK - PHP - PKR - PLN - PYG - QAR - RON - RSD - RUB - RWF - SAR - SBD - SCR - SDG - SEK - SGD - SHP - SLL - SOS - SRD - SSP - STD - STN - SVC - SYP - SZL - THB - TJS - TMT - TND - TOP - TRY - TTD - TWD - TZS - UAH - UGX - USD - USN - USS - UYI - UYU - UZS - VEF - VES - VND - VUV - WST - XAF - XCD - XOF - XPF - YER - ZAR - ZMW - ZWL responseCode: type: string description: | Response from the processor. - `A` - The processor approved the transaction. - `D` - The processor declined the transaction. responseMessage: maxLength: 48 minLength: 1 type: string description: Description of the response from the processor. processorResponseCode: type: string description: Original response code that the processor sent. description: Object that contains information about the transaction. examples: createdBankTransferPaymentStoreToken: summary: Store Token Bank Transfer Payment description: Bank Transfer Payment with ACH payload and token storage value: &ref_172 paymentId: M2MJOG6O2Y processingTerminalId: '1017' order: orderId: orderpop123 dateTime: '2023-07-25T14:08:45.179+01:00' description: sample order amount: 11110 currency: USD breakdown: subtotal: 10000 tip: type: percentage amount: 1010 percentage: 10 taxes: - name: VAT rate: 1 amount: 100 customer: contactMethods: - type: email value: joe@blogssoftware.com notificationLanguage: en bankAccount: type: ach secCode: web accountType: checking nameOnAccount: Joe Bloggs accountNumber: '****1010' routingNumber: '053200983' secureToken: secureTokenId: MREF_8d9b44e4-fd9c-45a7-b4b5-5e3d591dd385tK customerName: Joe Bloggs token: '2967534039611822' status: notValidated link: rel: self method: GET href: https://api.payroc.com/v1/processing-terminals/1017/secure-tokens/MREF_8d9b44e4-fd9c-45a7-b4b5-5e3d591dd385tK transactionResult: type: payment status: ready authorizedAmount: 11110 currency: USD responseCode: A responseMessage: NoError processorResponseCode: '0' headers: location: description: URI reference to created resource. style: simple explode: false schema: *ref_22 '400': description: Validation error content: application/problem+json: schema: type: object properties: *ref_8 required: *ref_9 examples: validationError: summary: Bad Request description: One or more validation errors occurred value: *ref_10 idempotentKeyMissing: summary: Idempotency key missing description: Idempotency key must be supplied value: *ref_23 idempotentKeyInUse: summary: Idempotency key in use description: Idempotency key in use value: *ref_26 '401': description: Identity could not be verified content: *ref_11 '403': description: Do not have permissions to perform this action content: *ref_12 '406': description: Not acceptable content: *ref_18 '409': description: Conflict content: *ref_79 '415': description: Unsupported media type content: *ref_80 '500': description: An error has occured content: *ref_13 get: tags: - Bank transfer payments summary: List payments description: Retrieve a list of payments. operationId: listBankTransferPayments parameters: - name: processingTerminalId in: query required: true description: Filter payments by the unique identifier that our gateway assigned to the terminal. schema: maxLength: 50 minLength: 4 type: string - name: orderId in: query description: Filter payments by the order ID. schema: maxLength: 24 minLength: 1 type: string - name: nameOnAccount in: query description: Filter payments by the account holder's name. schema: maxLength: 50 minLength: 1 type: string - name: last4 in: query description: Filter payments by the last four digits of the account number. schema: pattern: '[0-9]{4}' type: string - name: type in: query description: Filter payments by transaction type. schema: type: array items: type: string enum: - payment - accountVerification - name: status in: query description: Filter by the status of the payment. schema: type: array items: type: string enum: - ready - pending - declined - complete - admin - reversal - returned - name: dateFrom in: query description: Filter by payments that the merchant ran after a specific date. The date follows the ISO 8601 standard. schema: type: string format: date-time - name: dateTo in: query description: Filter by payments that the merchant ran before a specific date. The date follows the ISO 8601 standard. schema: type: string format: date-time - name: settlementState in: query description: Filter by the settlement status of the payment. schema: type: string enum: - settled - unsettled - name: settlementDate in: query description: Filter by payments settled on a specific date. The format is in **YYYY-MM-DD**. schema: type: string format: date - name: before in: query required: false description: Points to the resource identifier that you want to receive your results before. Typically, this is the first resource on the previous page. explode: false schema: *ref_29 example: '2571' - name: after in: query description: Points to the resource identifier that you want to receive your results after. Typically, this is the last resource on the previous page. schema: *ref_30 example: '8516' - name: limit in: query description: States the total amount of results the response is limited to. schema: *ref_31 example: 25 responses: '200': description: Successful request. Returns a list of payments. content: application/json: schema: required: &ref_405 - count - data - hasMore - limit type: object allOf: &ref_406 - type: object description: Contains the pagination properties that you use to navigate through a list of results. properties: *ref_32 - type: object properties: data: type: array description: Array of payments. items: required: *ref_170 type: object description: Object that contains information about the sale and the customer's bank details. properties: *ref_171 examples: paginatedResults: summary: Bank Transfer Payment description: Bank Transfer Payment value: &ref_508 limit: 2 count: 2 hasMore: true data: - paymentId: GTNOY9O4R4 processingTerminalId: '1017' order: orderId: '602' dateTime: '2023-05-16T11:53:18-04:00' description: sample order amount: 12100 currency: CAD breakdown: subtotal: 10000 tip: type: percentage amount: 1100 percentage: 10 taxes: - name: VAT rate: 10 amount: 1000 customer: contactMethods: - type: email value: joe@bloggssoftware.com notificationLanguage: en bankAccount: type: pad nameOnAccount: Joe Bloggs accountNumber: '*******8909' transitNumber: '12345' institutionNumber: '123' transactionResult: type: payment status: ready authorizedAmount: 12100 currency: CAD responseCode: A - paymentId: E29U8OU8Q4 processingTerminalId: '1017' order: orderId: '541' dateTime: '2023-05-16T11:52:56-04:00' description: test amount: 12100 currency: CAD breakdown: subtotal: 10000 tip: type: percentage amount: 1100 percentage: 10 taxes: - name: VAT rate: 10 amount: 1000 customer: contactMethods: - type: email value: joe@bloggssoftware.com notificationLanguage: en bankAccount: type: pad nameOnAccount: Joe Bloggs accountNumber: '*******8909' transitNumber: '12345' institutionNumber: '123' transactionResult: type: payment status: ready authorizedAmount: 12100 currency: CAD responseCode: A links: - rel: next method: get href: https://api.payroc.com/v1/bank-transfer-payments?limit=2&processingTerminalId=1017&after=E29U8OU8Q4 - rel: previous method: get href: https://api.payroc.com/v1//bank-transfer-payments?limit=2&processingTerminalId=1017&before=GTNOY9O4R4 noActivity: summary: No records found description: Valid request, but no records match the criteria. value: *ref_47 '400': description: Invalid request content: *ref_14 '401': description: Identity could not be verified content: *ref_11 '403': description: Do not have permissions to perform this action content: *ref_12 '406': description: Not acceptable content: *ref_18 '500': description: An error has occured content: *ref_13 /bank-transfer-payments/{paymentId}: get: tags: - Bank transfer payments summary: Retrieve payment description: Retrieve a specific payment. operationId: getBankTransferPayment parameters: - name: paymentId description: Unique identifier that our gateway assigned to the payment. in: path required: true schema: maxLength: 10 minLength: 10 type: string responses: '200': description: Successful request. Returns the specific payment. content: application/json: schema: required: *ref_170 type: object description: Object that contains information about the sale and the customer's bank details. properties: *ref_171 examples: bankTransferPayment: summary: Store Token Bank Transfer Payment description: Bank Transfer Payment with ACH payload and token storage value: *ref_172 '400': description: Invalid request content: *ref_14 '401': description: Identity could not be verified content: *ref_11 '403': description: Do not have permissions to perform this action content: *ref_12 '404': description: Resource not found content: *ref_17 '406': description: Not acceptable content: *ref_18 '500': description: An error has occured content: *ref_13 /bank-transfer-payments/{paymentId}/reverse: post: tags: - Bank transfer payments summary: Reverse payment description: Cancel a payment in an open batch. 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 for the identifier. schema: *ref_21 example: 8e03978e-40d5-43e8-bc93-6894a57f9324 - name: paymentId description: Unique identifier that our gateway assigned to the payment. in: path required: true schema: maxLength: 10 minLength: 10 type: string responses: '200': description: Successful request. We voided the payment. content: application/json: schema: required: *ref_170 type: object description: Object that contains information about the sale and the customer's bank details. properties: *ref_171 examples: reverseBankTransferPayment: summary: Reverse Bank Transfer Payment description: Reverse Bank Transfer Payment value: &ref_510 paymentId: JKNIJXNZAK processingTerminalId: '1017' order: orderId: '157' dateTime: '2023-05-16T11:54:43-04:00' description: sample order amount: 12100 currency: CAD breakdown: subtotal: 10000 tip: type: percentage percentage: 10 taxes: - name: VAT rate: 10 amount: 1000 customer: contactMethods: - type: email value: joe@bloggssoftware.com notificationLanguage: en bankAccount: type: pad nameOnAccount: Joe Bloggs accountNumber: '*******8909' transitNumber: '12345' institutionNumber: '123' transactionResult: type: payment status: reversal authorizedAmount: 12100 currency: CAD responseCode: A '400': description: Validation error content: application/problem+json: schema: type: object properties: *ref_8 required: *ref_9 examples: validationError: summary: Bad Request description: One or more validation errors occurred value: *ref_10 idempotentKeyMissing: summary: Idempotency key missing description: Idempotency key must be supplied value: *ref_23 idempotentKeyInUse: summary: Idempotency key in use description: Idempotency key in use value: *ref_26 '401': description: Identity could not be verified content: *ref_11 '403': description: Do not have permissions to perform this action content: *ref_12 '404': description: Resource not found content: *ref_17 '406': description: Not acceptable content: *ref_18 '409': description: Conflict content: *ref_79 '415': description: Unsupported media type content: *ref_80 '500': description: An error has occured content: *ref_13 /bank-transfer-payments/{paymentId}/refund: post: tags: - Bank transfer payments summary: Refund payment description: Refund a payment. 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 for the identifier. schema: *ref_21 example: 8e03978e-40d5-43e8-bc93-6894a57f9324 - name: paymentId description: Unique identifier that our gateway assigned to the payment. in: path required: true schema: maxLength: 10 minLength: 10 type: string requestBody: content: application/json: schema: required: &ref_409 - amount - description type: object description: Object that contains information about the payment that you want to refund. properties: &ref_410 amount: type: integer format: int64 description: Total amount of the refund. The value is in the currency's lowest denomination, for example, cents. description: maxLength: 100 minLength: 1 type: string description: Description of the refund. examples: refundBankTransferPayment: summary: Refund Bank Transfer Payment description: Refund Bank Transfer Payment value: &ref_511 amount: 10000 description: amount to refund required: true responses: '200': description: Successful request. We refunded the payment. content: application/json: schema: required: *ref_170 type: object description: Object that contains information about the sale and the customer's bank details. properties: *ref_171 examples: bankTransferPayment: summary: Reverse Bank Transfer Payment description: Reverse Bank Transfer Payment value: &ref_512 paymentId: M12F8SUHGM processingTerminalId: '1017' order: orderId: '243' dateTime: '2023-07-25T22:57:11+01:00' description: amount to refund amount: 11110 currency: CAD breakdown: subtotal: 10000 tip: type: percentage amount: 1010 percentage: 10 taxes: - name: VAT rate: 1 amount: 100 customer: contactMethods: - type: email value: joe@blogssoftware.com notificationLanguage: en bankAccount: type: pad nameOnAccount: Joe Bloggs accountNumber: '****9031' transitNumber: '14574' institutionNumber: '644' secureToken: secureTokenId: MREF_465772d1-ab4e-4881-8052-5021a745ed18Df customerName: Joe Bloggs token: '2967536686508441' status: notValidated link: rel: self method: GET href: https://api.payroc.com/v1/processing-terminals/1017/secure-tokens/MREF_465772d1-ab4e-4881-8052-5021a745ed18Df transactionResult: type: payment status: reversal authorizedAmount: 11110 currency: CAD responseCode: A '400': description: Validation error content: application/problem+json: schema: type: object properties: *ref_8 required: *ref_9 examples: validationError: summary: Bad Request description: One or more validation errors occurred value: *ref_10 idempotentKeyMissing: summary: Idempotency key missing description: Idempotency key must be supplied value: *ref_23 idempotentKeyInUse: summary: Idempotency key in use description: Idempotency key in use value: *ref_26 '401': description: Identity could not be verified content: *ref_11 '403': description: Do not have permissions to perform this action content: *ref_12 '404': description: Resource not found content: *ref_17 '406': description: Not acceptable content: *ref_18 '409': description: Conflict content: *ref_79 '415': description: Unsupported media type content: *ref_80 '500': description: An error has occured content: *ref_13 /bank-transfer-payments/{paymentId}/represent: post: tags: - Bank transfer payments summary: Re-present payment description: Re-present a customer's bank account details if the first payment was declined. 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 for the identifier. schema: *ref_21 example: 8e03978e-40d5-43e8-bc93-6894a57f9324 - name: paymentId description: Unique identifier that our gateway assigned to the rejected payment. in: path required: true schema: maxLength: 10 minLength: 10 type: string requestBody: content: application/json: schema: required: &ref_411 - paymentMethod type: object description: Object that contains the paymentMethod object. properties: &ref_412 paymentMethod: type: object description: Object that contains information about the customer's payment details. oneOf: - required: *ref_161 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_162 examples: representBankTransferPayment: summary: Representment Bank Transfer Payment description: Representment Bank Transfer Payment value: &ref_513 paymentMethod: type: ach accountType: checking nameOnAccount: Joe Bloggs accountNumber: '49100130' routingNumber: '292735277' secCode: TEL responses: '200': description: Successful request. We processed the payment. content: application/json: schema: required: *ref_170 type: object description: Object that contains information about the sale and the customer's bank details. properties: *ref_171 examples: bankTransferPayment: summary: Store Token Bank Transfer Payment description: Bank Transfer Payment with ACH payload and token storage value: *ref_172 '400': description: Validation error content: application/problem+json: schema: type: object properties: *ref_8 required: *ref_9 examples: validationError: summary: Bad Request description: One or more validation errors occurred value: *ref_10 idempotentKeyMissing: summary: Idempotency key missing description: Idempotency key must be supplied value: *ref_23 idempotentKeyInUse: summary: Idempotency key in use description: Idempotency key in use value: *ref_26 '401': description: Identity could not be verified content: *ref_11 '403': description: Do not have permissions to perform this action content: *ref_12 '404': description: Resource not found content: *ref_17 '406': description: Not acceptable content: *ref_18 '409': description: Conflict content: *ref_79 '415': description: Unsupported media type content: *ref_80 '500': description: An error has occured content: *ref_13 /bank-transfer-refunds: post: tags: - Bank transfer refunds summary: Create 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 for the identifier. schema: *ref_21 example: 8e03978e-40d5-43e8-bc93-6894a57f9324 description: | Send a refund to a customer's bank account. The refund transaction is not linked to the previous transaction. *Note**: This function is available to only certain merchant accounts. requestBody: content: application/json: schema: required: &ref_415 - order - processingTerminalId - refundMethod type: object properties: &ref_416 processingTerminalId: maxLength: 50 minLength: 4 type: string description: Unique identifier that our gateway assigned to the terminal. order: description: Object that contains information about the order. required: &ref_173 - amount - currency - description - orderId type: object allOf: &ref_174 - required: *ref_124 type: object description: Object that contains details about the transaction. properties: *ref_125 - 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. 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. description: maxLength: 256 minLength: 0 type: string description: Description of the transaction. amount: type: integer format: int64 description: Total amount of the transaction. The value is in the currency's lowest denomination, for example, cents. currency: type: string description: Currency code for the transaction. This code follows the ISO 4217 standard. enum: - AED - AFN - ALL - AMD - ANG - AOA - ARS - AUD - AWG - AZN - BAM - BBD - BDT - BGN - BHD - BIF - BMD - BND - BOB - BOV - BRL - BSD - BTN - BWP - BYR - BZD - CAD - CDF - CHE - CHF - CHW - CLF - CLP - CNY - COP - COU - CRC - CUC - CUP - CVE - CZK - DJF - DKK - DOP - DZD - EGP - ERN - ETB - EUR - FJD - FKP - GBP - GEL - GHS - GIP - GMD - GNF - GTQ - GYD - HKD - HNL - HRK - HTG - HUF - IDR - ILS - INR - IQD - IRR - ISK - JMD - JOD - JPY - KES - KGS - KHR - KMF - KPW - KRW - KWD - KYD - KZT - LAK - LBP - LKR - LRD - LSL - LTL - LVL - LYD - MAD - MDL - MGA - MKD - MMK - MNT - MOP - MRO - MRU - MUR - MVR - MWK - MXN - MXV - MYR - MZN - NAD - NGN - NIO - NOK - NPR - NZD - OMR - PAB - PEN - PGK - PHP - PKR - PLN - PYG - QAR - RON - RSD - RUB - RWF - SAR - SBD - SCR - SDG - SEK - SGD - SHP - SLL - SOS - SRD - SSP - STD - STN - SVC - SYP - SZL - THB - TJS - TMT - TND - TOP - TRY - TTD - TWD - TZS - UAH - UGX - USD - USN - USS - UYI - UYU - UZS - VEF - VES - VND - VUV - WST - XAF - XCD - XOF - XPF - YER - ZAR - ZMW - ZWL refundMethod: description: Object that contains information about how the merchant refunds the customer. type: object oneOf: - required: *ref_161 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_162 - required: *ref_108 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_109 examples: bankTransferUnreferencedRefundRequest: summary: Bank Transfer Unreferenced Refund description: Bank Transfer Unreferenced Refund value: &ref_515 processingTerminalId: '1017' order: orderId: 314 description: refund example amount: 1000 currency: USD customer: notificationLanguage: en contactMethods: - type: email value: joe@blogssoftware.com refundMethod: type: ach secCode: web accountType: checking nameOnAccount: Joe Bloggs accountNumber: '32183159' routingNumber: '063100277' required: true responses: '201': description: Successful request. We sent the refund to the customer's bank account. content: application/json: schema: required: &ref_181 - bankAccount - order - processingTerminalId - refundId - transactionResult type: object properties: &ref_182 refundId: maxLength: 10 minLength: 10 type: string description: Unique identifier that our gateway assigned to the refund. processingTerminalId: maxLength: 50 minLength: 4 type: string description: Unique identifier that our gateway assigned to the terminal. order: description: Object that contains information about the order. required: *ref_173 type: object allOf: *ref_174 customer: type: object properties: *ref_167 description: Object that contains information about the customer. bankAccount: description: Object that contains information about the bank account. type: object oneOf: - required: *ref_175 type: object title: ACH account description: Object that contains the customer's account details. properties: *ref_176 - required: *ref_177 type: object title: PAD account description: Object that contains the customer's account details. properties: *ref_178 payment: required: *ref_139 type: object description: Object that contains information about a payment. properties: *ref_140 transactionResult: required: *ref_179 type: object readOnly: true properties: *ref_180 description: Object that contains information about the transaction. examples: bankTransferUnreferencedRefundResponse: summary: Bank Transfer Unreferenced Refund description: Bank Transfer Unreferenced Refund value: &ref_183 refundId: JH58KQ5K5E processingTerminalId: '1017' order: orderId: '314' dateTime: '2023-05-17T09:24:11.693-04:00' description: refund example amount: 50000 currency: USD customer: contactMethods: - type: email value: joe@bloggssoftware.com notificationLanguage: en bankAccount: type: ach secCode: web accountType: checking nameOnAccount: Joe Bloggs accountNumber: '****3159' routingNumber: '*****0277' transactionResult: type: unreferencedRefund status: ready authorizedAmount: -50000 currency: USD responseCode: A responseMessage: NoError processorResponseCode: '0' headers: location: description: URI reference to created resource. style: simple explode: false schema: *ref_22 '400': description: Validation error content: application/problem+json: schema: type: object properties: *ref_8 required: *ref_9 examples: validationError: summary: Bad Request description: One or more validation errors occurred value: *ref_10 idempotentKeyMissing: summary: Idempotency key missing description: Idempotency key must be supplied value: *ref_23 idempotentKeyInUse: summary: Idempotency key in use description: Idempotency key in use value: *ref_26 '401': description: Identity could not be verified content: *ref_11 '403': description: Do not have permissions to perform this action content: *ref_12 '406': description: Not acceptable content: *ref_18 '409': description: Conflict content: *ref_79 '415': description: Unsupported media type content: *ref_80 '500': description: An error has occured content: *ref_13 get: tags: - Bank transfer refunds summary: List refunds description: Return a list of refund transactions. operationId: listBankTransferRefunds parameters: - name: processingTerminalId in: query required: true description: Filter by the unique identifier that our gateway assigned to the terminal. schema: maxLength: 50 minLength: 4 type: string - name: orderId in: query description: Filter by the order ID. schema: maxLength: 24 minLength: 1 type: string - name: nameOnAccount in: query description: Filter by the account holder's name. schema: maxLength: 50 minLength: 1 type: string - name: last4 in: query description: Filter by the last four digits of the account number. schema: pattern: '[0-9]{4}' type: string - name: type description: Filter refunds by transaction type. in: query schema: type: array items: type: string enum: - refund - unreferencedRefund - name: status in: query description: Filter by the status of the refund. schema: type: array items: type: string enum: - ready - pending - declined - complete - admin - reversal - returned - name: dateFrom in: query description: Filter by refunds that the merchant ran after a specific date. The date format follows the ISO-8601 standard. schema: type: string format: date-time - name: dateTo in: query description: Filter by the refunds that the merchant ran before a specific date. The date format follows the ISO-8601 standard. schema: type: string format: date-time - name: settlementState in: query description: Filter by the settlement status of the refund. schema: type: string enum: - settled - unsettled - name: settlementDate in: query description: Filter by refund transactions settled on a specific date. The date format is **YYYY-MM-DD**. schema: type: string format: date - name: before in: query required: false description: Points to the resource identifier that you want to receive your results before. Typically, this is the first resource on the previous page. explode: false schema: *ref_29 example: '2571' - name: after in: query description: Points to the resource identifier that you want to receive your results after. Typically, this is the last resource on the previous page. schema: *ref_30 example: '8516' - name: limit in: query description: States the total amount of results the response is limited to. schema: *ref_31 example: 25 responses: '200': description: Successful request. Returns a list of refund transactions. content: application/json: schema: required: &ref_413 - count - data - hasMore - limit type: object allOf: &ref_414 - type: object description: Contains the pagination properties that you use to navigate through a list of results. properties: *ref_32 - type: object properties: data: type: array description: Array of refund transactions. items: required: *ref_181 type: object properties: *ref_182 examples: paginatedResults: summary: Paginated Bank Transfer Unreferenced Refund description: Paginated Bank Transfer Unreferenced Refund value: &ref_514 limit: 2 count: 2 hasMore: true data: - refundId: DYDJ5KHRT4 processingTerminalId: '1017' order: orderId: '304' dateTime: '2023-05-17T09:23:41-04:00' description: refund example amount: 100000 currency: USD customer: contactMethods: - type: email value: joe@joesoftware.com notificationLanguage: en bankAccount: type: ach secCode: web accountType: checking nameOnAccount: Joe Bloggs accountNumber: '****3159' routingNumber: '*****0277' transactionResult: type: unreferencedRefund status: ready authorizedAmount: -100000 currency: USD responseCode: A responseMessage: NoError processorResponseCode: '0' - refundId: B6ZOFZNVOP processingTerminalId: '1017' order: orderId: '355' dateTime: '2023-05-17T09:21:30-04:00' description: refund example amount: 12000 currency: USD customer: contactMethods: - type: email value: joe@bloggssoftware.com notificationLanguage: en bankAccount: type: ach secCode: web accountType: checking nameOnAccount: Joe Bloggs accountNumber: '****3159' routingNumber: '*****0277' transactionResult: type: unreferencedRefund status: ready authorizedAmount: -12000 currency: USD responseCode: A responseMessage: NoError processorResponseCode: '0' links: - rel: next method: get href: https://api.payroc.com/v1/bank-transfer-refunds?limit=2&processingTerminalId=1017&after=B6ZOFZNVOP - rel: previous method: get href: https://api.payroc.com/v1/bank-transfer-refunds?processingTerminalId=1017&limit=2&before=DYDJ5KHRT4 noActivity: summary: No records found description: Valid request, but no records match the criteria. value: *ref_47 '400': description: Invalid request content: *ref_14 '401': description: Identity could not be verified content: *ref_11 '403': description: Do not have permissions to perform this action content: *ref_12 '406': description: Not acceptable content: *ref_18 '500': description: An error has occured content: *ref_13 /bank-transfer-refunds/{refundId}: get: tags: - Bank transfer refunds summary: Retrieve refund operationId: getBankTransferRefund description: Return a specific refund transaction. parameters: - name: refundId description: Unique identifier that our gateway assigned to the refund. in: path required: true schema: maxLength: 10 minLength: 10 type: string responses: '200': description: Successful request. Returns the specific refund. content: application/json: schema: required: *ref_181 type: object properties: *ref_182 examples: bankTransferUnreferencedRefund: summary: Bank Transfer Unreferenced Refund description: Bank Transfer Unreferenced Refund value: *ref_183 '400': description: Invalid request content: *ref_14 '401': description: Identity could not be verified content: *ref_11 '403': description: Do not have permissions to perform this action content: *ref_12 '404': description: Resource not found content: *ref_17 '406': description: Not acceptable content: *ref_18 '500': description: An error has occured content: *ref_13 /bank-transfer-refunds/{refundId}/reverse: post: tags: - Bank transfer refunds summary: Reverse refund operationId: reverseBankTransferRefund description: Void a refund transaction. parameters: - name: Idempotency-Key in: header required: true description: Unique identifier that you generate for each request. You must use the UUID v4 format for the identifier. schema: *ref_21 example: 8e03978e-40d5-43e8-bc93-6894a57f9324 - name: refundId description: Unique identifier that our gateway assigned to the refund. in: path required: true schema: maxLength: 10 minLength: 10 type: string responses: '200': description: Successful request. We reversed the refund transaction. content: application/json: schema: required: *ref_181 type: object properties: *ref_182 examples: bankTransferUnreferencedRefund: summary: Bank Transfer Unreferenced Refund description: Bank Transfer Unreferenced Refund value: &ref_516 refundId: B5FK0CBP2D processingTerminalId: '1017' order: orderId: '622' dateTime: '2023-05-17T09:54:51-04:00' description: refund example amount: 1000 currency: USD customer: contactMethods: - type: email value: joe@bloggssoftware.com notificationLanguage: en bankAccount: type: ach secCode: web accountType: checking nameOnAccount: Joe Bloggs accountNumber: '****3159' routingNumber: '*****0277' transactionResult: type: unreferencedRefund status: reversal authorizedAmount: -1000 currency: USD responseCode: A responseMessage: NoError processorResponseCode: '0' '400': description: Validation error content: application/problem+json: schema: type: object properties: *ref_8 required: *ref_9 examples: validationError: summary: Bad Request description: One or more validation errors occurred value: *ref_10 idempotentKeyMissing: summary: Idempotency key missing description: Idempotency key must be supplied value: *ref_23 idempotentKeyInUse: summary: Idempotency key in use description: Idempotency key in use value: *ref_26 '401': description: Identity could not be verified content: *ref_11 '403': description: Do not have permissions to perform this action content: *ref_12 '404': description: Resource not found content: *ref_17 '406': description: Not acceptable content: *ref_18 '409': description: Conflict content: *ref_79 '415': description: Unsupported media type content: *ref_80 '500': description: An error has occured content: *ref_13 /bank-accounts/verify: post: tags: - Bank accounts summary: Verify a bank account operationId: verifyBankAccount description: Verify the customer's bank account details. parameters: - name: Idempotency-Key in: header required: true description: Unique identifier that you generate for each request. You must use the UUID v4 format for the identifier. schema: *ref_21 example: 8e03978e-40d5-43e8-bc93-6894a57f9324 requestBody: content: application/json: schema: required: &ref_417 - processingTerminalId - bankAccount type: object properties: &ref_418 processingTerminalId: maxLength: 50 minLength: 4 type: string description: Unique identifier that our gateway assigned to the terminal. bankAccount: description: Object that contains information about the bank account. type: object oneOf: - required: *ref_161 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_162 - required: *ref_163 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_164 examples: bankAccountVerificationRequestPad: summary: PAD Bank Account Verification Request description: Bank Account Verification Request for PAD value: &ref_517 processingTerminalId: '1017' bankAccount: type: pad accountType: checking nameOnAccount: Joe Bloggs accountNumber: '12345678909' routingNumber: '123456789' transitNumber: '12345' institutionNumber: '123' bankAccountVerificationRequestAch: summary: ACH Bank Account Verification Request description: Bank Account Verification Request for ACH value: &ref_518 processingTerminalId: '1017' bankAccount: type: ach accountType: checking nameOnAccount: Joe Bloggs accountNumber: '32183159' routingNumber: '063100277' 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_419 - processingTerminalId - verified type: object properties: &ref_420 processingTerminalId: maxLength: 50 minLength: 4 type: string description: Unique identifier that our gateway assigned to the terminal. 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. examples: bankAccountVerificationResponse: summary: Bank Account Verification Response description: Bank Account Verification Response value: &ref_519 processingTerminalId: '1017' verified: true '400': description: Validation error content: application/problem+json: schema: type: object properties: *ref_8 required: *ref_9 examples: validationError: summary: Bad Request description: One or more validation errors occurred value: *ref_10 idempotentKeyMissing: summary: Idempotency key missing description: Idempotency key must be supplied value: *ref_23 idempotentKeyInUse: summary: Idempotency key in use description: Idempotency key in use value: *ref_26 '401': description: Identity could not be verified content: *ref_11 '403': description: Do not have permissions to perform this action content: *ref_12 '404': description: Resource not found content: *ref_17 '406': description: Not acceptable content: *ref_18 '409': description: Conflict content: *ref_79 '415': description: Unsupported media type content: *ref_80 '500': description: An error has occured content: *ref_13 /merchant-platforms: summary: Provide capabilities to manage a merchant platform. post: tags: - Merchant platforms summary: Create merchant platform description: | Use this method to create the entity that represents a business, including its legal information and all its processing accounts. > **Note**: To add a processing account to an existing merchant platform, go to [Create a processing account](#createProcessingAccount). The response contains some fields that we require for other methods: - **merchantPlatformId** - Unique identifier that we assign to the merchant platform. Use the merchantPlatformId to retrieve and update information about the merchant platform. - **processingAccountId**- Unique identifier that we assign to each processing account. Use the processingAccountId to retrieve and update information about the processing account.
For more information about how to create a merchant platform, go to [Create a merchant platform.](/guides/integrate/boarding/merchant-platform) 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 for the identifier. schema: *ref_21 example: 8e03978e-40d5-43e8-bc93-6894a57f9324 requestBody: content: application/json: schema: type: object title: create merchant platform required: &ref_434 - business - processingAccounts properties: &ref_435 business: type: object description: Object that contains information about the business. title: business required: &ref_188 - name - taxId - contactMethods - addresses - organizationType properties: &ref_189 name: type: string description: Legal name of the business. maxLength: 100 example: Example Corp 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 country code for the country that the business operates in. The format follows the ISO-3166 standard. enum: - US example: US addresses: type: array minItems: 1 uniqueItems: true description: Array of address objects. items: oneOf: - title: Legal address required: &ref_421 - type - city - country - address1 - postalCode - state allOf: &ref_422 - type: object properties: 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: An array of contactMethod objects. Email should always be provided. items: oneOf: *ref_2 processingAccounts: description: Array of processingAccounts objects. type: array minItems: 1 items: required: &ref_197 - doingBusinessAs - owners - businessType - merchandiseOrServiceSold - businessStartDate - timezone - address - contactMethods - processing - funding - pricing - signature - categoryCode type: object properties: &ref_198 processingAccountId: type: integer 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_27 properties: *ref_28 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: Category code 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: type: string description: Time zone of the processing account. 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 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: oneOf: *ref_2 processing: type: object title: processing required: &ref_193 - transactionAmounts - monthlyAmounts - volumeBreakdown properties: &ref_194 merchantId: type: string description: Unique identifier that the acquiring platform assigns to the merchant. maxLength: 15 example: '444412365478965' 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: type: object required: - refunds - estimatedMonthlyTransactions - limits properties: naics: type: string description: North American Industry Classification System (NAICS) code. maxLength: 6 example: 44-45 previouslyTerminatedForAch: type: boolean default: false description: Indicates if the business or its principals were previously turned down for ACH processing. example: false refunds: 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: 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 supported transaction types. 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: Information around the type of cards that will be accepted. properties: debitOnly: type: boolean default: false description: Indicates if the merchant accepts only debit 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: 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: 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: 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 allOf: &ref_428 - type: object description: Object that contains information about the funding schedule of the processing account. properties: &ref_195 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. **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. We apply this fee if the value for fundingSchedule is `sameday` or `nextday`. example: 1999 default: 0 dailyDiscount: type: boolean description: Indicator if fees should be taken on a daily basis. example: false - type: object properties: fundingAccounts: description: Array of fundingAccounts objects. minItems: 1 maxItems: 2 writeOnly: true type: array items: required: *ref_19 type: object title: funding account properties: *ref_20 pricing: type: object description: Object that contains pricing information. oneOf: &ref_432 - type: object title: Pricing intent required: &ref_429 - type - pricingIntentId properties: &ref_430 type: type: string enum: - intent example: intent pricingIntentId: type: integer description: Unique identifier of the pricing intent. example: 6123 - type: object title: Pricing agreement allOf: &ref_431 - type: object properties: type: type: string enum: - agreement example: agreement required: - type - 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_184 properties: *ref_185 discriminator: &ref_433 propertyName: type mapping: intent: '#/components/schemas/pricingTemplate' agreement: '#/components/schemas/pricingAgreement' signature: type: string description: | Method used to capture the owner's signature. **Note:** If you request the owner’s signature by email and they don’t respond, use our Reminders endpoint to create a reminder and to send another email. enum: - requestedViaEmail - requestedViaDirectLink example: requestedViaEmail contacts: type: array description: Array of contact objects. items: type: object title: contact required: &ref_206 - type - firstName - lastName - identifiers - contactMethods properties: &ref_207 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_186 type: object title: identifier properties: *ref_187 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: oneOf: *ref_2 metadata: type: object additionalProperties: type: string description: Object that you can send to include custom data in the request. 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_521 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: 35.4 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: 44-45 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 cardsAccepted: - visa - mastercard specialityCards: americanExpressDirect: enabled: true merchantNumber: abc1234567 electronicBenefitsTransfer: enabled: true fnsNumber: abc1234 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: internalRef: '2345' pricing: type: intent pricingIntentId: 6123 signature: 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_190 - business - processingAccounts properties: &ref_191 merchantPlatformId: type: string readOnly: true description: Unique identifier of the merchant platform. example: '12345' createdDate: type: string format: date-time example: '2020-09-08T12:00:00.000Z' readOnly: true description: Date that the merchant platform was created. lastModifiedDate: type: string format: date-time example: '2020-09-08T12:00:00.000Z' readOnly: true description: Date that the merchant platform was last modified. business: type: object description: Object that contains information about the business. title: business required: *ref_188 properties: *ref_189 processingAccounts: readOnly: true description: Array of processingAccount objects required: - doingBusinessAs - status type: array items: type: object title: processingAccount properties: processingAccountId: type: string description: Unique identifier of 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. 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 example: processingAccount description: Relationship to the parent resource. href: type: string example: https://api.payroc.com/v1/processing-accounts/38765 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 containing the method we used to capture the owner's signature. oneOf: &ref_196 - title: Signature by direct link description: We return a link to the pricing agreement in the response. type: object required: &ref_423 - type properties: &ref_424 type: type: string description: Method used to capture the owner's signature. enum: - requestedViaDirectLink example: requestedViaDirectLink link: allOf: - type: object readOnly: true description: Link to sign agreement - type: object description: Object that contains information about a HATEOAS link. If we can't match a dispute to a transaction, we don't return a 'link' object. properties: *ref_3 required: *ref_4 example: *ref_5 example: rel: agreement href: https://us.agreementexpress.net/mv2/viewer2.jsp?docId=00000000-0000-0000-0000-000000000000 method: get - title: Signature by email description: Owner's signature by email. type: object required: &ref_425 - type properties: &ref_426 type: type: string description: Method used to capture the owner's signature. enum: - requestedViaEmail example: requestedViaEmail 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 description: Object that contains information about a HATEOAS link. If we can't match a dispute to a transaction, we don't return a 'link' object. properties: *ref_3 required: *ref_4 example: *ref_5 examples: created: summary: Created merchant platform description: New merchant platform created value: &ref_522 merchantPlatformId: '12345' createdDate: '2020-09-08T12:00:00.000Z' lastModifiedDate: '2020-09-08T12: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_523 merchantPlatformId: '12346' createdDate: '2020-09-08T12:00:00.000Z' lastModifiedDate: '2020-09-08T12: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. style: simple explode: false schema: type: string '400': description: Validation error. content: application/problem+json: schema: type: object properties: *ref_8 required: *ref_9 examples: validationError: summary: Bad Request description: One or more validation errors occurred value: *ref_10 idempotentKeyMissing: summary: Idempotency key missing description: Idempotency key must be supplied value: *ref_23 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_201 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_202 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_203 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 RewardPay or RewardPayChoice at the same time. description: You can't select Daily Discount with a RewardPay or RewardPayChoice pricing plan. To select Daily Discount, choose a different pricing plan. value: &ref_204 type: https://docs.payroc.com/api/errors#daily-discount-and-reward-pay-conflict title: Cannot select Daily Discount and RewardPay or 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_11 '403': description: Do not have permissions to perform this action content: *ref_12 '406': description: Not acceptable content: *ref_18 '409': description: Conflict content: application/problem+json: schema: type: object properties: *ref_24 required: *ref_25 examples: idempotentKeyInUse: summary: Idempotency key in use description: Idempotency key in use value: *ref_26 taxIdInUse: summary: Tax ID in use description: The tax ID supplied is already in use. value: &ref_524 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_525 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_13 get: tags: - Merchant platforms summary: List merchant platforms description: Use this method to retrieve a [paginated](/api/pagination) list of the merchant platforms that are linked to the ISV's account. operationId: listMerchantPlatforms parameters: - name: before in: query required: false description: Points to the resource identifier that you want to receive your results before. Typically, this is the first resource on the previous page. explode: false schema: *ref_29 example: '2571' - name: after in: query description: Points to the resource identifier that you want to receive your results after. Typically, this is the last resource on the previous page. schema: *ref_30 example: '8516' - name: limit in: query description: States the total amount of results the response is limited to. schema: *ref_31 example: 25 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_427 - type: object description: Contains the pagination properties that you use to navigate through a list of results. properties: *ref_32 - type: object properties: data: type: array description: Array of merchantPlatform objects. items: type: object title: merchant required: *ref_190 properties: *ref_191 examples: listMerchantPlatforms: summary: Paginated list of merchant platforms description: Retrieve a list of merchant platforms associated with your account. value: &ref_520 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: '2020-09-08T12:00:00.000Z' lastModifiedDate: '2020-09-08T12: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: '2020-09-08T12:00:00.000Z' lastModifiedDate: '2020-09-08T12: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_47 '401': description: Identity could not be verified content: *ref_11 '403': description: Do not have permissions to perform this action content: *ref_12 '406': description: Not acceptable content: *ref_18 '500': description: An error has occured content: *ref_13 /merchant-platforms/{merchantPlatformId}: get: tags: - Merchant platforms summary: Retrieve merchant platform description: | Use this method to retrieve information about a merchant platform, including its legal information and processing accounts. Include the merchantPlatformId that we sent you when you created the merchant platform. operationId: getMerchantAcccounts parameters: - name: merchantPlatformId in: path description: Unique identifier of the merchant platform. required: true style: simple explode: false schema: &ref_192 type: string example: '12345' responses: '200': description: Successful request. Returns the merchant platform. content: application/json: schema: type: object title: merchant required: *ref_190 properties: *ref_191 examples: retrievedMerchantPlatforms: summary: Retrieve merchant platform description: Retrieve a merchant platform. value: &ref_526 merchantPlatformId: '12345' createdDate: '2020-09-08T12:00:00.000Z' lastModifiedDate: '2020-09-08T12: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_14 '401': description: Identity could not be verified content: *ref_11 '403': description: Do not have permissions to perform this action content: *ref_12 '404': description: Resource not found content: *ref_17 '406': description: Not acceptable content: *ref_18 '500': description: An error has occured content: *ref_13 /merchant-platforms/{merchantPlatformId}/processing-accounts: get: tags: - Merchant platforms summary: List merchant platform's processing accounts description: | Use this method to retrieve a paginated list of processing accounts associated with a merchant platform. When you created the merchant platform, we sent you its merchantPlatformId in the response. Send this merchantPlatformId as a path parameter in your endpoint. > **Note**: By default, we return only open processing accounts. To include closed processing accounts, send a value of `true` for the includeClosed query parameter. operationId: listMerchantLocations parameters: - name: merchantPlatformId in: path description: Unique identifier of the merchant platform. required: true style: simple explode: false schema: *ref_192 - name: before in: query required: false description: Points to the resource identifier that you want to receive your results before. Typically, this is the first resource on the previous page. explode: false schema: *ref_29 example: '2571' - name: after in: query description: Points to the resource identifier that you want to receive your results after. Typically, this is the last resource on the previous page. schema: *ref_30 example: '8516' - name: limit in: query description: States the total amount of results the response is limited to. schema: *ref_31 example: 25 - in: query name: includeClosed description: Indicates if you want to return closed processing accounts. This includes processing accounts that have a status of `terminated`, `cancelled`, or `rejected`. required: false schema: type: boolean default: 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_438 - type: object description: Contains the pagination properties that you use to navigate through a list of results. properties: *ref_32 - type: object properties: data: type: array description: Array of processingAccount objects. items: required: &ref_199 - doingBusinessAs - owners - businessType - merchandiseOrServiceSold - timezone - address - contactMethods - processing - funding - pricing - signature - categoryCode type: object properties: &ref_200 processingAccountId: type: string readOnly: true description: Unique identifier of the processing account. example: '38765' createdDate: type: string format: date-time readOnly: true description: Date that the processing account was created. example: '2020-09-08T12:00:00.000Z' lastModifiedDate: type: string format: date-time readOnly: true description: Date that the processing account was last modified. example: '2020-09-08T12: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. 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: type: integer example: 4564 firstName: type: string example: Jane lastName: type: string example: Doe link: type: object properties: rel: type: string description: The relationship to the parent resource. example: owner href: type: string description: The link to the resource. example: https://api.payroc.com/v1/owners/1543 method: type: string description: HTTP method for retrieving the 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: Category code 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: type: string description: Time zone for the processing account. 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 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. Atleast one contactMethod must be an email address. items: oneOf: *ref_2 processing: type: object title: processing required: *ref_193 properties: *ref_194 funding: type: object description: Object that contains funding information. allOf: &ref_437 - type: object description: Object that contains information about the funding schedule of the processing account. properties: *ref_195 - type: object properties: fundingAccounts: minItems: 1 maxItems: 2 readOnly: true type: array items: type: object title: funding account summary properties: &ref_436 fundingAccountId: type: integer readOnly: true example: 123 status: type: string readOnly: true example: pending enum: - approved - rejected - pending link: readOnly: true type: object description: Object that contains information about a HATEOAS link. If we can't match a dispute to a transaction, we don't return a 'link' object. properties: *ref_3 required: *ref_4 example: *ref_5 pricing: type: object description: Object that contains pricing information. properties: link: type: object description: HATEOAS link for pricing information. properties: rel: type: string example: pricing description: Relationship to the parent resource. href: type: string example: https://api.payroc.com/v1/processing-account/38765/pricing description: Link to the resource. method: type: string example: get description: HTTP method you can use to retrieve the 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 containing the method we used to capture the owner's signature. oneOf: *ref_196 metadata: type: object additionalProperties: type: string description: Object that you can send to include custom data in the request. example: customerId: '2345' links: type: array description: Array of useful links related to your request. items: type: object description: Object that contains information about a HATEOAS link. If we can't match a dispute to a transaction, we don't return a 'link' object. properties: *ref_3 required: *ref_4 example: *ref_5 example: [] examples: listProcessingAccounts: summary: Paginated list of processing account description: Retrieve processing accounts associated with a merchant platform. value: &ref_527 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: '2020-09-08T12:00:00.000Z' lastModifiedDate: '2020-09-08T12: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: '441222' 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 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-account/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: '2020-09-08T12:00:00.000Z' lastModifiedDate: '2020-09-08T12: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-account/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_47 '400': description: Invalid request content: *ref_14 '401': description: Identity could not be verified content: *ref_11 '403': description: Do not have permissions to perform this action content: *ref_12 '406': description: Not acceptable content: *ref_18 '500': description: An error has occured content: *ref_13 post: tags: - Merchant platforms summary: Create processing account description: | Use this method to create a processing account and add it to a merchant platform. > **Note**: You can create and add a processing account only to an existing merchant platform. If you have not already created a merchant platform, go to [Create a merchant platform.](#createMerchant) In the response we return a processingAccountId for the processing account, which you need for the following methods. - [Retrieve processing account](#getProcessingAcccounts) - [List processing account's funding accounts](#listProcessingAccountsFundingAccounts) - [List contacts](#listProcessingAccountContacts) - [Get a processing account pricing agreement](#retrieveProcessingAccountPricing) - [List owners](#listMerchantOwners) - [Create reminder for processing account](#createReminder) operationId: createProcessingAccount parameters: - name: merchantPlatformId in: path description: Unique identifier of the merchant platform. required: true style: simple explode: false schema: *ref_192 - name: Idempotency-Key in: header required: true description: Unique identifier that you generate for each request. You must use the UUID v4 format for the identifier. schema: *ref_21 example: 8e03978e-40d5-43e8-bc93-6894a57f9324 requestBody: content: application/json: schema: required: *ref_197 type: object properties: *ref_198 examples: retrievedMerchantPlatforms: summary: Create merchant platform description: Create a merchant platform. value: &ref_528 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: 35.4 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: 44-45 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 cardsAccepted: - visa - mastercard specialityCards: americanExpressDirect: enabled: true merchantNumber: abc1234567 electronicBenefitsTransfer: enabled: true fnsNumber: abc1234 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: internalRef: '2345' pricing: type: intent pricingIntentId: 6123 signature: 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_199 type: object properties: *ref_200 examples: retrievedMerchantPlatforms: summary: Retrieve merchant platform description: Retrieve a merchant platform. value: &ref_529 processingAccountId: '12345' createdDate: '2020-09-08T12:00:00.000Z' lastModifiedDate: '2020-09-08T12: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: 44-45 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 cardsAccepted: - visa - mastercard specialityCards: americanExpressDirect: enabled: true merchantNumber: abc1234567 electronicBenefitsTransfer: enabled: true fnsNumber: abc1234 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-account/123 pricing: link: rel: pricing href: https://api.payroc.com/v1/processing-account/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. style: simple explode: false schema: type: string '400': description: Validation error. content: application/problem+json: schema: type: object properties: *ref_8 required: *ref_9 examples: validationError: summary: Bad Request description: One or more validation errors occurred value: *ref_10 idempotentKeyMissing: summary: Idempotency key missing description: Idempotency key must be supplied value: *ref_23 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_201 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_202 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_203 dailyDiscountAndRewardPayConflict: summary: Cannot select Daily Discount and RewardPay or RewardPayChoice at the same time. description: You can't select Daily Discount with a RewardPay or RewardPayChoice pricing plan. To select Daily Discount, choose a different pricing plan. value: *ref_204 '401': description: Identity could not be verified content: *ref_11 '404': description: Resource not found content: *ref_17 '406': description: Not acceptable content: *ref_18 '409': description: Conflict content: application/problem+json: schema: type: object properties: *ref_24 required: *ref_25 examples: idempotentKeyInUse: summary: Idempotency key in use description: Idempotency key in use value: *ref_26 '500': description: An error has occured content: *ref_13 /processing-accounts/{processingAccountId}: get: tags: - Processing accounts summary: Retrieve processing account description: Retrieve a specific processing account. operationId: getProcessingAcccounts parameters: - name: processingAccountId in: path description: Unique identifier of the processing account. required: true style: simple explode: false schema: &ref_205 type: string example: '12345' responses: '200': description: Successful request. Returns the processing account. content: application/json: schema: required: *ref_199 type: object properties: *ref_200 examples: processingAccount: summary: Retrieve processing account description: Retrieve a specific processing account. value: &ref_530 processingAccountId: '38765' createdDate: '2020-09-08T12:00:00.000Z' lastModifiedDate: '2020-09-08T12: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: 44-45 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 cardsAccepted: - visa - mastercard specialityCards: americanExpressDirect: enabled: true merchantNumber: abc1234567 electronicBenefitsTransfer: enabled: true fnsNumber: abc1234 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-account/123 pricing: link: rel: pricing href: https://api.payroc.com/v1/processing-account/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_14 '401': description: Identity could not be verified content: *ref_11 '403': description: Do not have permissions to perform this action content: *ref_12 '404': description: Resource not found content: *ref_17 '406': description: Not acceptable content: *ref_18 '500': description: An error has occured content: *ref_13 /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 of the processing account. required: true style: simple explode: false schema: *ref_205 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 fundingAccount objects. items: required: *ref_19 type: object title: funding account properties: *ref_20 examples: fundingAccounts: summary: List of funding accounts description: List of funding accounts associated with a processing account. value: &ref_531 - fundingAccountId: 123 createdDate: '2020-09-08T12:00:00.000Z' lastModifiedDate: '2020-09-08T12:00:00.000Z' status: approved type: checking use: creditAndDebit nameOnAccount: Jane Doe paymentMethods: - type: ach value: routingNumber: '*****6789' accountNumber: '******7890' metadata: internalRef: '2345' links: - rel: parent href: https://api.payroc.com/v1/processing-accounts/38765 method: get - fundingAccountId: 124 createdDate: '2021-01-08T12:00:00.000Z' lastModifiedDate: '2021-01-08T12:00:00.000Z' status: pending type: checking use: creditAndDebit nameOnAccount: Jane Doe paymentMethods: - type: ach value: routingNumber: '*****8725' accountNumber: '******3491' metadata: internalRef: '2346' links: - rel: parent href: https://api.payroc.com/v1/processing-accounts/38765 method: get '400': description: Invalid request content: *ref_14 '401': description: Identity could not be verified content: *ref_11 '403': description: Identity could not be verified content: *ref_11 '404': description: Resource not found content: *ref_17 '406': description: Not acceptable content: *ref_18 '500': description: An error has occured content: *ref_13 /processing-accounts/{processingAccountId}/contacts: get: tags: - Processing accounts summary: List contacts description: Retrieve a list of contacts associated with a processing account. operationId: listProcessingAccountContacts parameters: - name: processingAccountId in: path description: Unique identifier of the processing account. required: true style: simple explode: false schema: *ref_205 - name: before in: query required: false description: Points to the resource identifier that you want to receive your results before. Typically, this is the first resource on the previous page. explode: false schema: *ref_29 example: '2571' - name: after in: query description: Points to the resource identifier that you want to receive your results after. Typically, this is the last resource on the previous page. schema: *ref_30 example: '8516' - name: limit in: query description: States the total amount of results the response is limited to. schema: *ref_31 example: 25 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_439 - type: object description: Contains the pagination properties that you use to navigate through a list of results. properties: *ref_32 - type: object properties: data: type: array description: An array of contact objects. items: type: object title: contact required: *ref_206 properties: *ref_207 examples: paginatedContacts: summary: Paginated list of processing account contacts description: List of contacts associated with a processing account. value: &ref_532 limit: 2 count: 2 hasMore: true links: - rel: previous method: get href: https://api.payroc.com/v1/processing-accounts/38765/contacts?before=4564&limit=2 - rel: next method: get href: https://api.payroc.com/v1/processing-accounts/38765/contacts?after=4565&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: 12346 type: representative firstName: Fred middleName: Jim lastName: Nerk identifiers: - type: nationalId value: xxxxx9876 contactMethods: - type: phone value: '2025550110' - type: mobile value: '85645787451' - type: email value: fred.nerk@example.com noActivity: summary: No records found description: Valid request, but no records match the criteria. value: *ref_47 '400': description: Invalid request content: *ref_14 '401': description: Identity could not be verified content: *ref_11 '403': description: Identity could not be verified content: *ref_11 '406': description: Not acceptable content: *ref_18 '500': description: An error has occured content: *ref_13 /processing-accounts/{processingAccountId}/pricing: get: summary: Get processing account pricing agreement description: Retrieve a pricing agreement for a processing account. operationId: retrieveProcessingAccountPricing tags: - Processing accounts parameters: - name: processingAccountId in: path description: Unique identifier of the processing account. required: true style: simple explode: false schema: *ref_205 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_184 properties: *ref_185 examples: paginatedContacts: summary: Get processing account pricing agreement description: Retrieve a pricing agreement for a processing account. value: &ref_533 country: US version: '4.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: 1500 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 additionalServiceMonthly: 0 '400': description: Invalid request content: *ref_14 '401': description: Identity could not be verified content: *ref_11 '403': description: Do not have permissions to perform this action content: *ref_12 '404': description: Resource not found content: *ref_17 '406': description: Not acceptable content: *ref_18 '500': description: An error has occured content: *ref_13 /processing-accounts/{processingAccountId}/owners: get: tags: - Processing accounts summary: List owners description: Retrieve owners associated with a processing account. operationId: listMerchantOwners parameters: - name: processingAccountId in: path description: Unique identifier of the processing account. required: true style: simple explode: false schema: *ref_205 - name: before in: query required: false description: Points to the resource identifier that you want to receive your results before. Typically, this is the first resource on the previous page. explode: false schema: *ref_29 example: '2571' - name: after in: query description: Points to the resource identifier that you want to receive your results after. Typically, this is the last resource on the previous page. schema: *ref_30 example: '8516' - name: limit in: query description: States the total amount of results the response is limited to. schema: *ref_31 example: 25 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_440 - type: object description: Contains the pagination properties that you use to navigate through a list of results. properties: *ref_32 - type: object properties: data: type: array description: Array of owner objects. items: type: object title: owner required: *ref_27 properties: *ref_28 examples: listProcessingAccountOwners: summary: Paginated list of processing account owners description: Retrieve owners associated with a processing account. value: &ref_534 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=4565&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: 49 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 title: CEO isControlProng: false isAuthorizedSignatory: true noActivity: summary: No records found description: Valid request, but no records match the criteria. value: *ref_47 '400': description: Invalid request content: *ref_14 '401': description: Identity could not be verified content: *ref_11 '404': description: Resource not found content: *ref_17 '406': description: Not acceptable content: *ref_18 '500': description: An error has occured content: *ref_13 /processing-accounts/{processingAccountId}/reminders: post: tags: - Processing accounts 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. operationId: createReminder parameters: - name: processingAccountId in: path description: Unique identifier of the processing account. required: true style: simple explode: false schema: *ref_205 requestBody: content: application/json: schema: oneOf: - type: object required: &ref_208 - type properties: &ref_209 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_535 type: pricingAgreement responses: '201': description: Successful request. We sent the email to the merchant. content: application/json: schema: oneOf: - type: object required: *ref_208 properties: *ref_209 examples: reminderCreated: summary: '' description: '' value: &ref_536 reminderId: '1234567' type: pricingAgreement '400': description: Bad request content: application/problem+json: schema: type: object properties: *ref_8 required: *ref_9 examples: badRequest: summary: Bad Request description: One or more validation errors occurred value: *ref_10 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_537 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_538 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_539 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. '403': description: Do not have permissions to perform this action content: *ref_12 '404': description: Resource not found content: *ref_17 '500': description: An error has occured content: *ref_13 /contacts/{contactId}: get: tags: - Contacts summary: Retrieve contact description: Retrieve a specific contact. operationId: getContact parameters: - name: contactId in: path description: Unique identifier for the contact. required: true style: simple explode: false schema: &ref_210 type: integer example: 1543 responses: '200': description: Successful request. Returns the requested contact. content: application/json: schema: type: object title: contact required: *ref_206 properties: *ref_207 examples: contact: summary: Contact object description: Contact object value: &ref_540 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_14 '401': description: Identity could not be verified content: *ref_11 '403': description: Do not have permissions to perform this action content: *ref_12 '404': description: Resource not found content: *ref_17 '500': description: An error has occured content: *ref_13 put: tags: - Contacts summary: Update contact description: Update a specific contact. operationId: updateContact parameters: - name: contactId in: path description: Unique identifier for the contact. required: true style: simple explode: false schema: *ref_210 example: 1543 requestBody: content: application/json: schema: type: object title: contact required: *ref_206 properties: *ref_207 examples: updateContact: summary: Update contact description: Update a specific contact. value: &ref_541 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_8 required: *ref_9 examples: validationError: summary: Bad Request description: One or more validation errors occurred value: *ref_10 '401': description: Identity could not be verified content: *ref_11 '403': description: Do not have permissions to perform this action content: *ref_12 '404': description: Resource not found content: *ref_17 '406': description: Not acceptable content: *ref_18 '500': description: An error has occured content: *ref_13 delete: tags: - Contacts summary: Delete contact description: Delete a contact. operationId: deleteContact parameters: - name: contactId in: path description: Unique identifier for the contact. required: true style: simple explode: false schema: *ref_210 example: 1543 responses: '204': description: Successful request. We deleted the contact. '400': description: Invalid request content: *ref_14 '401': description: Identity could not be verified content: *ref_11 '403': description: Do not have permissions to perform this action content: *ref_12 '404': description: Resource not found content: *ref_17 '500': description: An error has occured content: *ref_13 components: securitySchemes: bearerAuth: type: http description: 'Example: Authorization: Bearer ' scheme: bearer bearerFormat: JWT parameters: before: name: before in: query required: false description: Points to the resource identifier that you want to receive your results before. Typically, this is the first resource on the previous page. explode: false schema: *ref_29 example: '2571' after: name: after in: query description: Points to the resource identifier that you want to receive your results after. Typically, this is the last resource on the previous page. schema: *ref_30 example: '8516' limit: name: limit in: query description: States the total amount of results the response is limited to. schema: *ref_31 example: 25 idempotencyKey: name: Idempotency-Key in: header required: true description: Unique identifier that you generate for each request. You must use the UUID v4 format for the identifier. schema: *ref_21 example: 8e03978e-40d5-43e8-bc93-6894a57f9324 recipientId: name: recipientId description: Unique identifier of the funding recipient. in: path required: true style: simple explode: false schema: *ref_15 fundingAccountId: name: fundingAccountId in: path required: true description: Unique identifier of the funding account. style: simple explode: false schema: *ref_33 ownerId: name: ownerId in: path description: Unique identifier for the owner. required: true style: simple explode: false schema: *ref_34 example: 4564 pricingIntentId: in: path name: pricingIntentId schema: *ref_211 required: true description: Unique identifier of the pricing intent. example: '5' dateFrom: name: dateFrom in: query description: Retrieve activity that occured since `dateFrom`. We can return activity from only the last two years. required: true schema: *ref_212 dateTo: name: dateTo in: query required: true description: Retrieve activity that occured before `dateTo`. schema: *ref_213 instructionId: name: instructionId in: path required: true description: Unique identifier of the funding instruction. schema: *ref_214 merchantId: name: merchantId in: query description: Unique identifier of the merchant. schema: *ref_58 example: '4525644354' batchId: name: batchId description: Unique identifier of the batch. in: path required: true style: simple schema: *ref_215 example: 12345 keyDate: name: date in: query required: true description: Date to retrieve results from. The format of this value is **YYYY-MM-DD**. You must provide either the 'batchId' or the 'date'. schema: *ref_64 example: '2021-09-05' batchIdQuery: name: batchId in: query required: true description: Unique identifier of the batch. You must provide either the 'batchId' or the 'date'. schema: *ref_65 example: 12345 transactionType: name: transactionType in: query required: false description: Type of transaction. schema: *ref_216 transactionId: name: transactionId description: Unique identifier of the transaction. in: path required: true style: simple schema: *ref_217 authorizationId: name: authorizationId description: Unique identifier of the authorization. in: path required: true style: simple schema: *ref_218 disputeId: name: disputeId description: Unique identifier of the dispute. in: path required: true style: simple schema: *ref_219 merchantPlatformId: name: merchantPlatformId in: path description: Unique identifier of the merchant platform. required: true style: simple explode: false schema: *ref_192 processingAccountId: name: processingAccountId in: path description: Unique identifier of the processing account. required: true style: simple explode: false schema: *ref_205 contactId: name: contactId in: path description: Unique identifier for the contact. required: true style: simple explode: false schema: *ref_210 example: 1543 schemas: '400': type: object properties: *ref_8 required: *ref_9 '401': type: object properties: *ref_220 required: *ref_221 '403': type: object properties: *ref_222 required: *ref_223 '404': type: object properties: *ref_224 required: *ref_225 '406': type: object properties: *ref_226 required: *ref_227 '409': type: object properties: *ref_24 required: *ref_25 '415': type: object properties: *ref_228 required: *ref_229 '500': type: object properties: *ref_230 required: *ref_231 link: type: object description: Object that contains information about a HATEOAS link. If we can't match a dispute to a transaction, we don't return a 'link' object. properties: *ref_3 required: *ref_4 example: *ref_5 paginatedList: type: object description: Contains the pagination properties that you use to navigate through a list of results. properties: *ref_32 address: required: *ref_0 type: object title: address description: Object that contains information about the address. properties: *ref_1 contactMethodEmail: required: *ref_232 type: object title: Email contact method properties: *ref_233 contactMethodPhone: required: *ref_234 type: object title: Phone number contact method properties: *ref_235 contactMethodMobile: required: *ref_236 type: object title: Mobile number contact method properties: *ref_237 contactMethodFax: required: *ref_238 type: object title: Fax number contact method properties: *ref_239 contactMethod: oneOf: *ref_2 fundingRecipient: required: *ref_6 type: object title: funding recipient properties: *ref_7 paginatedFundRecipients: type: object title: paginated funding recipients allOf: *ref_240 identifier: required: *ref_186 type: object title: identifier properties: *ref_187 ownerRelationship: required: *ref_241 type: object title: Owner relationship description: Object that contains information about the owner's relationship to the business. properties: *ref_242 owner: type: object title: owner required: *ref_27 properties: *ref_28 PaymentMethodAch: type: object title: ACH payment method properties: *ref_243 paymentMethods: uniqueItems: true type: array description: Array of PaymentMethodAch objects. xml: *ref_244 items: *ref_245 fundingAccount: required: *ref_19 type: object title: funding account properties: *ref_20 createFundingRecipient: required: *ref_246 type: object title: create funding recipient properties: *ref_247 listFundingAccounts: type: object title: paginated funding accounts allOf: *ref_248 baseIntent: type: object title: base pricing intent description: Object that contains information about the base fees. properties: *ref_249 required: *ref_250 baseUs: type: object title: US base fees description: Object that contains information about U.S. base fees. properties: *ref_251 required: *ref_252 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_35 pinDebit: type: object required: *ref_36 properties: *ref_37 electronicBenefitsTransfer: type: object required: *ref_38 properties: *ref_39 enhancedInterchange: type: object required: *ref_40 properties: *ref_41 specialityCards: type: object required: *ref_42 properties: *ref_43 interchangePlus: type: object title: Interchange Plus Plan description: Object that contains information about Interchange Plus. properties: *ref_253 required: *ref_254 qualRates: type: object required: *ref_44 properties: *ref_45 interchangePlusTiered3: type: object title: Interchange Plus with three tiers description: Object that contains information about Interchange Plus with three tiers. properties: *ref_255 required: *ref_256 tiered3: type: object title: Tiered pricing with three tiers description: Object that contains information about tiered pricing with three tiers. properties: *ref_257 required: *ref_258 qualRatesWithPremium: type: object allOf: *ref_46 tiered4: type: object title: Tiered pricing with four tiers description: Object that contains information about tiered pricing with four tiers. properties: *ref_259 required: *ref_260 qualRatesWithPremiumAndRegulated: type: object allOf: *ref_261 tiered6: type: object title: Tiered pricing with six tiers description: Object that contains information about tiered pricing with six tiers. properties: *ref_262 required: *ref_263 flatRate: type: object title: Flat Rate Plan description: Object that contains information about Flat Rate. properties: *ref_264 required: *ref_265 consumerChoice: type: object title: Consumer Choice Plan description: Object that contains information about ConsumerChoice. properties: *ref_266 required: *ref_267 rewardPay: type: object title: RewardPay Plan description: Object that contains information about RewardPay. properties: *ref_268 required: *ref_269 rewardPayChoice: type: object title: RewardPayChoice Plan description: Object that contains information about RewardPayChoice. properties: *ref_270 required: *ref_271 ach: type: object properties: *ref_272 processorFeesUs: type: object title: US processor fees description: Object that contains information about U.S. processor fees. properties: *ref_273 gatewayUs: type: object description: Object that contains information about the gateway fees. title: gateway fees properties: *ref_274 required: *ref_275 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_184 properties: *ref_185 pricingIntent4.0: type: object title: pricing intent version 4.0 description: Object that contains information about a pricing intent for Merchant Processing Agreement (MPA) 4.0. allOf: *ref_276 pricingIntent: type: object title: pricing intent description: Object that contains information about a pricing intent. oneOf: *ref_48 paginatedPricingIntent: type: object title: paginated pricing intents description: Object that contains information about your pricing intents. allOf: *ref_277 patchDocument: description: JSONPatch document, specified in RFC 6902. required: *ref_278 properties: *ref_279 patchRequest: type: array description: A JSONPatch document as defined by RFC 6902 example: *ref_77 items: *ref_78 instruction: type: object description: Inform the payfac what to do with the specified funds. ** title: funding instruction properties: *ref_51 merchantBalance: type: object description: Object that contains information about the total funds available to the merchant. title: merchant balance properties: *ref_280 activityRecord: type: object description: Array of activityRecord objects. title: activity record properties: *ref_281 required: *ref_282 merchantSummary: type: object title: merchant summary description: Object that contains information about the merchant. properties: *ref_59 example: *ref_60 batch: type: object title: batch properties: *ref_56 settledSummary: type: object title: settlement summary description: Object that contains information about the settlement. properties: *ref_283 batchSummary: type: object 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. nullable: true properties: *ref_66 cardSummary: type: object title: card summary description: Object that contains information about the card. properties: *ref_67 authorizationSummary: type: object title: authorization summary description: Object that contains information about the authorization. properties: *ref_284 transaction: type: object title: transaction description: Object that contains information about the transaction. properties: *ref_63 transactionSummary: type: object title: transaction summary description: Object that contains summary information about the transaction. properties: *ref_69 authorization: type: object title: authorization description: Object that contains information about the authorization. properties: *ref_68 disputeStatus: type: object title: dispute status description: Object that contains information about the current status of the dispute. properties: *ref_70 dispute: type: object title: dispute description: Object that contains information about the dispute. properties: *ref_285 tax: required: *ref_102 type: object properties: *ref_103 subscriptionBreakdown: required: *ref_71 type: object description: | Object that contains information about the taxes that apply to the transaction. properties: *ref_72 subscriptionOrder: type: object properties: *ref_73 setupOrder: type: object description: Object that contains information about the initial cost that a customer pays to set up the subscription. allOf: *ref_286 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_81 paymentPlan: required: *ref_74 type: object properties: *ref_75 paymentPlanPaginatedList: required: *ref_287 type: object allOf: *ref_288 paymentPlanSummary: required: *ref_289 type: object properties: *ref_290 secureTokenSummary: required: *ref_86 type: object description: Object that contains information about the secure token. properties: *ref_87 subscriptionPaymentOrder: description: Object that contains information about the initial cost that a customer pays to set up the subscription. type: object allOf: *ref_82 subscriptionState: required: *ref_88 type: object properties: *ref_89 description: A snapshot of the subscription's current state. subscription: required: *ref_83 type: object properties: *ref_84 subscriptionPaginatedList: required: *ref_291 type: object allOf: *ref_292 secureTokenPayload: required: *ref_108 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_109 subscriptionRequest: required: *ref_293 type: object properties: *ref_294 subscriptionPaymentRequest: required: *ref_295 properties: *ref_296 paymentSummary: required: *ref_139 type: object description: Object that contains information about a payment. properties: *ref_140 subscriptionPayment: required: *ref_297 type: object properties: *ref_298 shipping: description: Object that contains information about the customer and their shipping address. type: object properties: *ref_121 customer: type: object description: Customer contact and address details. properties: *ref_98 achSource: required: *ref_299 type: object title: ACH account description: Object that contains the customer's account details. properties: *ref_300 padSource: required: *ref_301 type: object title: PAD account description: Object that contains the customer's account details. properties: *ref_302 cardSource: required: *ref_303 type: object title: Card description: Object that contains the customer's card details. properties: *ref_304 secureToken: required: *ref_99 type: object description: Object that contains information about the secure token. properties: *ref_100 secureTokenPaginatedList: required: *ref_305 type: object allOf: *ref_306 ipAddress: required: *ref_104 type: object writeOnly: true description: Object that contains information about the IP address of the device that sent the request. properties: *ref_105 achPayload: required: *ref_161 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_162 padPayload: required: *ref_163 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_164 deviceConfig: required: *ref_307 type: object properties: *ref_308 description: Object that contains information about the configuration of the POS terminal. device: required: *ref_90 type: object properties: *ref_91 description: Object that contains information about the physical device the merchant used to capture the customer’s card details. rawCardDetails: required: *ref_309 type: object title: Raw description: Object that contains information about the unencrypted card details. properties: *ref_310 encryptionCapableDevice: required: *ref_92 type: object description: Object that contains information about the encryption details of the POS terminal. allOf: *ref_93 iccCardDetails: required: *ref_311 type: object title: Chip description: Object that contains information about the Integrated Circuit Card (ICC). properties: *ref_312 fullyEncryptedKeyedDataFormat: required: *ref_313 type: object title: Encrypted description: Object that contains information about the encrypted card data for keyed transactions. properties: *ref_314 partiallyEncryptedKeyedDataFormat: required: *ref_315 type: object title: Partially encrypted description: Object that contains information about the partially-encrypted card data for keyed transactions. properties: *ref_316 plainTextKeyedDataFormat: required: *ref_317 type: object title: Unencrypted description: Object that contains information about the plain-text card data for keyed transactions. properties: *ref_318 dukptPinDetails: required: *ref_94 type: object title: Encrypted description: Object that contains information about encrypted PIN details. properties: *ref_95 ebtDetails: required: *ref_129 type: object description: Object that contains information about the Electronic Benefit Transfer (EBT) transaction. properties: *ref_130 voucher: required: *ref_319 type: object properties: *ref_320 description: | Object that contains information about the EBT voucher. **Note:** Voucher is available only for EBT Cash benefit accounts. ebtDetailsWithVoucher: required: *ref_96 type: object description: Object that contains information about the Electronic Benefit Transfer (EBT) transaction. allOf: *ref_97 keyedCardDetails: required: *ref_321 type: object title: Keyed description: Object that contains information about the keyed card details. properties: *ref_322 encryptedSwipedDataFormat: required: *ref_323 type: object title: Encrypted description: Object that contains information about the encrypted swiped card data. properties: *ref_324 plainTextSwipedDataFormat: required: *ref_325 type: object title: Unencrypted description: Object that contains information about plain-text swiped card data. properties: *ref_326 swipedCardDetails: required: *ref_327 type: object title: Swiped description: Object that contains information about the customer’s card details for swiped transactions. properties: *ref_328 cardPayload: required: *ref_106 type: object writeOnly: true title: Card description: Object that contains information about the customer’s payment card. properties: *ref_107 gatewayThreeDSecure: required: *ref_110 type: object title: Gateway description: Object that contains the 3-D Secure information from our gateway. properties: *ref_111 thirdPartyThreeDSecure: required: *ref_112 type: object title: Third party description: Object that contains the 3-D Secure information from a third party. properties: *ref_113 tokenizationRequest: required: *ref_329 type: object properties: *ref_330 order: required: *ref_124 type: object description: Object that contains details about the transaction. properties: *ref_125 tip: required: *ref_119 type: object description: Object that contains information about the tip. properties: *ref_120 surcharge: type: object description: | Object that contains information about the surcharge. properties: *ref_331 choiceRate: required: *ref_332 type: object readOnly: true properties: *ref_333 description: | The choice rate. **Note:** This field is required if dual pricing was offered. dualPricing: required: *ref_334 type: object description: Object that contains information about dual pricing. properties: *ref_335 breakdown: required: *ref_126 type: object description: Object that contains information about the breakdown of the transaction. properties: *ref_127 convenienceFee: required: *ref_336 type: object readOnly: true description: Object that contains convenience fee information for the transaction. properties: *ref_337 lineItem: required: *ref_338 type: object description: List of line items. properties: *ref_339 itemizedBreakdown: required: *ref_122 type: object description: Object that contains information about the breakdown of the transaction. allOf: *ref_123 dccOffer: required: *ref_133 type: object properties: *ref_134 description: Object that contains the exchange rates offer for a foreign card. firstTxnReferenceData: type: object description: Object that contains information about the initial payment for the payment instruction. properties: *ref_340 standingInstructions: required: *ref_341 type: object description: If you don't use our Subscriptions mechanism, include this section to configure your standing/recurring orders. properties: *ref_342 paymentOrder: required: *ref_114 type: object description: Object that contains information about the payment. allOf: *ref_115 securityCheck: type: object properties: *ref_343 description: Object that contains information about card verification and security checks. emvTag: required: *ref_344 type: object description: Object that contains information about the EMV tag. properties: *ref_345 cardBalance: required: *ref_346 type: object properties: *ref_347 description: Object that contains information about the total funds available in the card. card: required: *ref_137 type: object properties: *ref_138 description: Object that contains information about the card. refundSummary: required: *ref_168 type: object description: Object that contains information about a refund. properties: *ref_169 supportedOperations: type: array items: *ref_141 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`. - `setAsDeclined` - Set the transaction’s status to `declined`. transactionResult: required: *ref_142 type: object properties: *ref_143 description: Object that contains information about the transaction response details. payment: required: *ref_116 type: object properties: *ref_117 paymentPaginatedList: required: *ref_348 type: object allOf: *ref_349 digitalWalletPayload: required: *ref_157 type: object writeOnly: true title: Digital wallet description: Object that contains information about the payment details in the customer’s digital wallet. properties: *ref_158 rawPinDetails: required: *ref_350 type: object title: Unencrypted description: Object that contains information about the unencrypted PIN details. properties: *ref_351 singleUseTokenPayload: required: *ref_155 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_156 credentialOnFile: type: object description: Object that contains information about saving the customer’s payment details. properties: *ref_128 offlineProcessing: required: *ref_352 type: object description: Object that contains information about the transaction if the merchant ran it when the terminal was offline. properties: *ref_353 paymentRequest: required: *ref_354 type: object properties: *ref_355 breakdownAdjustment: type: object description: Object that contains information about the tip amount of a transaction. properties: *ref_356 orderAdjustment: required: *ref_357 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_358 statusAdjustment: required: *ref_147 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_148 customerAdjustment: required: *ref_149 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_150 signatureAdjustment: required: *ref_359 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_360 paymentAdjustment: required: *ref_361 type: object description: Object that contains the transaction adjustment object. properties: *ref_362 paymentCapture: description: Object that contains the details of the payment that the merchant wants to capture. type: object properties: *ref_363 paymentReversal: type: object properties: *ref_364 referencedRefund: description: Object that contains the details of the payment that the merchant wants to refund. required: *ref_365 type: object properties: *ref_366 paymentInstructionOrder: required: *ref_367 type: object description: Object that contains information about the payment. allOf: *ref_368 customizationOptions: type: object description: Object that contains available options to customize certain aspects of an instruction. properties: *ref_151 paymentInstructionRequest: required: *ref_369 type: object description: Object that contains the instructions for initiating a payment on a physical device. properties: *ref_370 deviceInstruction: type: object description: Object that contains information about the status of the instruction properties: *ref_152 paymentInstruction: required: *ref_131 type: object allOf: *ref_132 refundOrder: required: *ref_135 type: object description: Object that contains information about the refund. allOf: *ref_136 refund: required: *ref_144 type: object description: Object that contains information about the refund. properties: *ref_145 refundPaginatedList: required: *ref_371 type: object description: Object that contains information about refund objects. allOf: *ref_372 unreferencedRefund: required: *ref_373 type: object description: Refund a payment that is not linked to a previous transaction. Unreferenced refunds are available only on certain accounts. properties: *ref_374 refundAdjustment: required: *ref_375 type: object description: Object that contains information about the adjustment to the refund. properties: *ref_376 refundInstructionOrder: required: *ref_377 type: object description: Object that contains information about the refund. allOf: *ref_378 refundInstructionRequest: required: *ref_379 type: object description: Object that contains information about the instruction request to initiate a refund on a payment device. properties: *ref_380 refundInstruction: required: *ref_153 type: object allOf: *ref_154 cardVerificationRequest: required: *ref_381 type: object properties: *ref_382 cardVerificationResult: required: *ref_383 type: object properties: *ref_384 balanceInquiry: required: *ref_385 type: object properties: *ref_386 balance: required: *ref_387 type: object properties: *ref_388 cardBinPayload: required: *ref_389 type: object writeOnly: true title: Card BIN description: Object that contains information about the card's bank identification number (BIN). properties: *ref_390 binLookup: required: *ref_391 type: object properties: *ref_392 surcharging: required: *ref_393 type: object properties: *ref_394 description: Object that contains surcharge information. Our gateway returns this object only if the merchant adds a surcharge to transactions. cardInfo: required: *ref_159 type: object readOnly: true properties: *ref_160 description: Object that contains information about the card. fxRateInquiry: required: *ref_395 type: object properties: *ref_396 fxRateInquiryResult: required: *ref_397 type: object properties: *ref_398 description: Object that contains information about the currency conversion rate. fxRate: required: *ref_399 type: object description: Foreign exchange rate for the transaction. properties: *ref_400 bankTransferBreakdown: required: *ref_401 type: object description: Object that contains information about the taxes and tip amount on the transaction. properties: *ref_402 bankTransferPaymentOrder: required: *ref_165 type: object allOf: *ref_166 description: Object that contains information about the transaction. bankTransferCustomer: type: object properties: *ref_167 description: Object that contains information about the customer. achBankAccount: required: *ref_175 type: object title: ACH account description: Object that contains the customer's account details. properties: *ref_176 padBankAccount: required: *ref_177 type: object title: PAD account description: Object that contains the customer's account details. properties: *ref_178 bankTransferReturnSummary: required: *ref_403 type: object description: Object that contains information about a return. properties: *ref_404 bankTransferResult: required: *ref_179 type: object readOnly: true properties: *ref_180 description: Object that contains information about the transaction. bankTransferPayment: required: *ref_170 type: object description: Object that contains information about the sale and the customer's bank details. properties: *ref_171 bankTransferPaymentPaginatedList: required: *ref_405 type: object allOf: *ref_406 bankTransferPaymentRequest: required: *ref_407 type: object description: Object that contains information about the sale and the customer's bank details. properties: *ref_408 bankTransferReferencedRefund: required: *ref_409 type: object description: Object that contains information about the payment that you want to refund. properties: *ref_410 representment: required: *ref_411 type: object description: Object that contains the paymentMethod object. properties: *ref_412 bankTransferRefundOrder: description: Object that contains information about the order. required: *ref_173 type: object allOf: *ref_174 bankTransferRefund: required: *ref_181 type: object properties: *ref_182 bankTransferRefundPaginatedList: required: *ref_413 type: object allOf: *ref_414 bankTransferUnreferencedRefund: required: *ref_415 type: object properties: *ref_416 bankAccountVerificationRequest: required: *ref_417 type: object properties: *ref_418 bankAccountVerificationResult: required: *ref_419 type: object properties: *ref_420 legalAddress: title: Legal address required: *ref_421 allOf: *ref_422 business: type: object description: Object that contains information about the business. title: business required: *ref_188 properties: *ref_189 signatureByDirectLink: title: Signature by direct link description: We return a link to the pricing agreement in the response. type: object required: *ref_423 properties: *ref_424 signatureByEmail: title: Signature by email description: Owner's signature by email. type: object required: *ref_425 properties: *ref_426 signature: type: object description: Object containing the method we used to capture the owner's signature. oneOf: *ref_196 merchantPlatform: type: object title: merchant required: *ref_190 properties: *ref_191 paginatedMerchants: type: object title: paginated merchant platforms allOf: *ref_427 processing: type: object title: processing required: *ref_193 properties: *ref_194 commonFunding: type: object description: Object that contains information about the funding schedule of the processing account. properties: *ref_195 createFunding: type: object allOf: *ref_428 pricingTemplate: type: object title: Pricing intent required: *ref_429 properties: *ref_430 pricingAgreement: type: object title: Pricing agreement allOf: *ref_431 pricing: type: object description: Object that contains pricing information. oneOf: *ref_432 discriminator: *ref_433 contact: type: object title: contact required: *ref_206 properties: *ref_207 createProcessingAccount: required: *ref_197 type: object properties: *ref_198 createMerchantAccount: type: object title: create merchant platform required: *ref_434 properties: *ref_435 fundingAccountSummary: type: object title: funding account summary properties: *ref_436 funding: type: object description: Object that contains funding information. allOf: *ref_437 processingAccount: required: *ref_199 type: object properties: *ref_200 paginatedProcessingAccounts: type: object title: paginated processing accounts allOf: *ref_438 paginatedContacts: type: object title: paginated Contacts allOf: *ref_439 paginatedOwners: type: object title: paginated Owners allOf: *ref_440 pricingAgreementReminder: type: object required: *ref_208 properties: *ref_209 examples: paginatedFundRecipients: summary: Paginated funding recipients. description: Paginated list of funding recipients. value: *ref_441 noActivity: summary: No records found description: Valid request, but no records match the criteria. value: *ref_47 validatorError: summary: Bad Request description: One or more validation errors occurred value: *ref_10 notAuthorized: summary: Not Authorized description: Your identity could not be verified value: *ref_442 forbidden: summary: Forbidden description: You do not have the required permission value: *ref_443 apiError: summary: Api error description: Unable to process your request. value: *ref_444 idempotentKeyMissing: summary: Idempotency key missing description: Idempotency key must be supplied value: *ref_23 kycCheckFailed: summary: KYC check failed description: KYC check failed value: *ref_16 notAcceptable: summary: Not acceptable description: Requested representation not supported value: *ref_445 idempotentKeyInUse: summary: Idempotency key in use description: Idempotency key in use value: *ref_26 fundingRecipient: summary: Funding recipient. description: Funding recipients. value: *ref_446 notFound: summary: Not found description: Resource could not be found value: *ref_447 fundingAccounts: summary: List of funding accounts description: List of funding accounts. value: *ref_448 fundingAccount: summary: Funding account description: Funding accounts. value: *ref_449 listFundingAccountExample: summary: Paginated funding accounts value: *ref_450 noResults: summary: No results found description: No results found value: *ref_451 fundingAccountExample: summary: Masked funding account example. value: *ref_452 retrievedOwner: summary: Retrieve owner description: Retrieve a specific owner. value: *ref_453 updateOwner: summary: Update owner description: Update a specific owner. value: *ref_454 paginatedPricingIntent: summary: Paginated pricing intent description: Example of a paginated pricing intent. value: *ref_455 modifyPricingIntent: summary: Create pricing intent description: Create a pricing intent. value: *ref_50 pricingIntent: summary: Pricing intent description: Pricing intent value: *ref_49 patchPricingIntentRealistic: summary: Partially update pricing intent description: | Partially update an existing pricing intent. Structure your request to follow the RFC 6902 standard. value: *ref_456 patchOperations: summary: Example patch operations that apply the RFC 6902 standard description: | Example patch operations that apply the RFC 6902 standard. value: *ref_457 listInstructionsExample: summary: Paginated instructions list value: *ref_458 parameterError: summary: Bad request description: One or more validation errors occurred. value: *ref_459 paginationError: summary: Bad request description: One or more validation errors occurred value: *ref_460 outsideRecordRange: summary: Bad request description: Requested data outside allowed range. value: *ref_461 newInstructionAccepted: summary: New instruction accepted. value: *ref_462 insufficientFunds: summary: Insufficient funds description: You do not have enough funds to complete the request. value: *ref_52 fundingAccountsRestricted: summary: Funding accounts restricted description: Funding accounts restricted. value: *ref_54 instructionIdError: summary: Bad request description: One or more validation errors occurred. value: *ref_53 canNotBeModified: summary: Cannot be modified description: Resource cannot be modified. value: *ref_55 listBalancesExample: summary: Paginated list of merchant balances description: Paginated list of merchant balances. value: *ref_463 paginatedList: summary: Paginated activity records description: Valid payfac account with activity for date range. value: *ref_464 paginatedBatches: summary: Paginated batches value: *ref_465 examples-parameterError: summary: Bad Request description: One or more validation errors occurred value: *ref_61 examples-paginationError: summary: Bad Request description: One or more validation errors occurred value: *ref_62 batchIdError: summary: Bad Request description: One or more validation errors occurred value: *ref_57 paginatedTransactions: summary: Paginated transactions value: *ref_466 transactionIdError: summary: Bad Request description: One or more validation errors occurred value: *ref_467 paginatedAuthorizations: summary: Paginated authorizations value: *ref_468 paginatedDisputes: summary: Paginated disputes value: *ref_469 paginatedPaymentPlan: summary: Payment Plan description: Payment Plan value: *ref_470 paymentPlanRequest: summary: Payment Plan description: Payment Plan value: *ref_471 paymentPlanResponse: summary: Payment Plan description: Payment Plan value: *ref_76 resourceExists: summary: Resource already exists description: Resource already exists value: *ref_472 unsupportedMediaType: summary: Unsupported media type description: The payload is in an unsupported format. value: *ref_473 paginatedSubscription: summary: Paginated Subscription description: Example of Paginated Subscription value: *ref_474 subscriptionRequest: summary: Subscription description: Subscription value: *ref_475 subscriptionResponse: summary: Subscription description: Subscription value: *ref_85 deactivateSubscription: summary: Deactivate subscription description: Deactivate a subscription value: *ref_476 subscriptionPaymentRequest: summary: Subscription manual payment description: Subscription manual payment value: *ref_477 subscriptionPaymentResponse: summary: Subscription manual payment description: Subscription manual payment value: *ref_478 paginatedSecureToken: summary: Paginated Secure Token description: Paginated Secure Token value: *ref_479 secureTokenRequest: summary: Secure Token description: Secure Token value: *ref_480 secureTokenResponse: summary: Secure Token description: Secure Token value: *ref_101 paginatedPayment: summary: Payment description: Payment value: *ref_481 paymentRequest: summary: Payment description: Payment value: *ref_482 paymentResponse: summary: Payment description: Payment value: *ref_118 adjustPaymentRequest: summary: Adjust Payment description: Adjust Payment value: *ref_483 adjustPaymentResponse: summary: Adjust Payment description: Adjust Payment value: *ref_484 reversalPaymentRequest: summary: Reversal Payment description: Reversal Payment value: *ref_485 reversalPaymentResponse: summary: Reversal Payment description: Reversal Payment value: *ref_486 refundPaymentRequest: summary: Refund Payment description: Refund Payment value: *ref_487 refundPaymentResponse: summary: Refund Payment description: Refund Payment value: *ref_488 paymentInstructionRequest: summary: Payment Instruction description: Submit an instruction for initiating a payment on a physical device. value: *ref_489 paymentInstructionInProgress: summary: Payment instruction description: Object that contains information about the progress of the payment instruction. value: *ref_490 paymentInstruction: summary: Payment instruction description: Object that contains information about the progress of the payment instruction. value: *ref_491 paginatedRefund: summary: Paginated Refund description: Paginated Refund value: *ref_492 refundRequest: summary: Refund description: Refund value: *ref_493 refundResponse: summary: Refund description: Refund value: *ref_146 adjustRefundRequest: summary: Adjust Refund description: Adjust Refund value: *ref_494 adjustRefundResponse: summary: Adjust Refund description: Adjust Refund value: *ref_495 reverseRefund: summary: Reverse Refund description: Reverse Refund value: *ref_496 refundInstructionRequest: summary: Refund instruction description: Submit an instruction for initiating a refund on a physical device. value: *ref_497 refundInstructionInProgress: summary: Refund instruction description: Object that contains information about the progress of the refund instruction. value: *ref_498 refundInstruction: summary: Refund instruction description: Object that contains information about the progress of the refund instruction. value: *ref_499 cardVerificationRequest: summary: Card Verification description: Card Verification value: *ref_500 cardVerificationResponse: summary: Card Verification description: Card Verification value: *ref_501 cardBalanceRequest: summary: Card Balance description: Card Balance value: *ref_502 cardBalanceResponse: summary: Card Balance description: Card Balance value: *ref_503 binLookupRequest: summary: BIN lookup description: BIN lookup value: *ref_504 binLookupResponse: summary: BIN lookup description: BIN lookup value: *ref_505 fxRateRequest: summary: Fx-Rate description: Fx-Rate value: *ref_506 fxRateResponse: summary: Fx-Rate description: Fx-Rate value: *ref_507 paginatedBankTransferPayment: summary: Bank Transfer Payment description: Bank Transfer Payment value: *ref_508 bankTransferPaymentRequestStoreToken: summary: Store Token Bank Transfer Payment description: Bank Transfer Payment with ACH payload and token storage value: *ref_509 bankTransferPaymentResponseStoreToken: summary: Store Token Bank Transfer Payment description: Bank Transfer Payment with ACH payload and token storage value: *ref_172 reverseBankTransferPayment: summary: Reverse Bank Transfer Payment description: Reverse Bank Transfer Payment value: *ref_510 refundBankTransferPaymentRequest: summary: Refund Bank Transfer Payment description: Refund Bank Transfer Payment value: *ref_511 refundBankTransferPaymentResponse: summary: Reverse Bank Transfer Payment description: Reverse Bank Transfer Payment value: *ref_512 representmentBankTransferPaymentRequest: summary: Representment Bank Transfer Payment description: Representment Bank Transfer Payment value: *ref_513 paginatedBankTransferUnreferencedRefund: summary: Paginated Bank Transfer Unreferenced Refund description: Paginated Bank Transfer Unreferenced Refund value: *ref_514 bankTransferUnreferencedRefundRequest: summary: Bank Transfer Unreferenced Refund description: Bank Transfer Unreferenced Refund value: *ref_515 bankTransferUnreferencedRefundResponse: summary: Bank Transfer Unreferenced Refund description: Bank Transfer Unreferenced Refund value: *ref_183 reverseBankTransferUnreferencedRefund: summary: Bank Transfer Unreferenced Refund description: Bank Transfer Unreferenced Refund value: *ref_516 bankAccountVerificationRequestPad: summary: PAD Bank Account Verification Request description: Bank Account Verification Request for PAD value: *ref_517 bankAccountVerificationRequestAch: summary: ACH Bank Account Verification Request description: Bank Account Verification Request for ACH value: *ref_518 bankAccountVerificationResponse: summary: Bank Account Verification Response description: Bank Account Verification Response value: *ref_519 listMerchantPlatforms: summary: Paginated list of merchant platforms description: Retrieve a list of merchant platforms associated with your account. value: *ref_520 createMerchantPlatform: summary: Create merchant platform description: Create a merchant platform. value: *ref_521 merchantPlatformCreated: summary: Created merchant platform description: New merchant platform created value: *ref_522 processingAccountFailed: summary: Failed processing account description: We successfully created the merchant platform, but failed to add one or more processing accounts. value: *ref_523 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_201 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_202 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_203 dailyDiscountAndRewardPayConflict: summary: Cannot select Daily Discount and RewardPay or RewardPayChoice at the same time. description: You can't select Daily Discount with a RewardPay or RewardPayChoice pricing plan. To select Daily Discount, choose a different pricing plan. value: *ref_204 taxIdInUse: summary: Tax ID in use description: The tax ID supplied is already in use. value: *ref_524 nationalIdInUse: summary: National ID in use description: One or more supplied national IDs are not unique. All national IDs must be unique. value: *ref_525 retrievedMerchantPlatforms: summary: Retrieve merchant platform description: Retrieve a merchant platform. value: *ref_526 listProcessingAccounts: summary: Paginated list of processing account description: Retrieve processing accounts associated with a merchant platform. value: *ref_527 createProcessingAccount: summary: Create merchant platform description: Create a merchant platform. value: *ref_528 processingAccountCreated: summary: Retrieve merchant platform description: Retrieve a merchant platform. value: *ref_529 retrieveProcessingAccount: summary: Retrieve processing account description: Retrieve a specific processing account. value: *ref_530 listProcessingAccountFundingAccounts: summary: List of funding accounts description: List of funding accounts associated with a processing account. value: *ref_531 listContactsPaginated: summary: Paginated list of processing account contacts description: List of contacts associated with a processing account. value: *ref_532 retrieveProcessingAccountPricingAgreement: summary: Get processing account pricing agreement description: Retrieve a pricing agreement for a processing account. value: *ref_533 listProcessingAccountOwners: summary: Paginated list of processing account owners description: Retrieve owners associated with a processing account. value: *ref_534 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_535 reminderCreated: summary: '' description: '' value: *ref_536 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_537 contractAlreadySigned: summary: Contract already signed description: We couldn’t resend the email because the merchant already signed the contract. value: *ref_538 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_539 contact: summary: Contact object description: Contact object value: *ref_540 updateContact: summary: Update contact description: Update a specific contact. value: *ref_541 responses: '400': description: Invalid request content: *ref_14 '401': description: Identity could not be verified content: *ref_11 '403': description: Do not have permissions to perform this action content: *ref_12 '404': description: Resource not found content: *ref_17 '406': description: Not acceptable content: *ref_18 '409': description: Conflict content: *ref_79 '415': description: Unsupported media type content: *ref_80 '500': description: An error has occured content: *ref_13 headers: location: description: URI reference to created resource. style: simple explode: false schema: *ref_22 x-tagGroups: - name: Boarding tags: - Contacts - Merchant platforms - Owners - Pricing intents - Processing accounts - name: Payroc Cloud tags: - Payment instructions - Refund instructions - name: Payments tags: - Bank accounts - Bank transfer payments - Bank transfer refunds - Cards - Currency conversion - Payments - Payment plans - Refunds - Secure tokens - Subscriptions - name: Funding tags: - Funding accounts - Funding instructions - Funding recipients - Funding activity - name: Reporting tags: - Settlement