starred/WireMock.Net
1
0
Fork 0
mirror of https://github.com/wiremock/WireMock.Net.git synced 2026-02-22 16:58:06 +01:00
Code Issues 32 Packages Projects Releases 10 Wiki Activity
Files
60eb3980f6b45f0e596cbab2a9d685afc81eb477
WireMock.Net/test/WireMock.Net.Tests/OpenApiParser/payroc-openapi-spec.yaml
Stef Heyenrath 4368e3cde6 1.7.x (#1268) 
* Fix construction of path in OpenApiParser (#1265)

* Server-Sent Events (#1269)

* Server Side Events

* fixes

* await HandleSseStringAsync(responseMessage, response, bodyData);

* 1.7.5-preview-01

* IBlockingQueue

* 1.7.5-preview-02 (03 April 2025)

* IBlockingQueue

* ...

* Support OpenApi V31 (#1279)

* Support OpenApi V31

* Update src/WireMock.Net.OpenApiParser/Extensions/OpenApiSchemaExtensions.cs

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* fx

---------

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* Add ProtoDefinitionHelper.FromDirectory (#1263)

* Add ProtoDefinitionHelper.FromDirectory

* .

* unix-windows

* move test

* imports in the proto files indeed should use a forward slash

* updates

* .

* private Func<IdOrTexts> ProtoDefinitionFunc()

* OpenTelemetry

* .

* fix path utils

---------

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
2025-04-23 11:51:44 +02:00

24188 lines
1002 KiB
YAML
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
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.<br/><br/>
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: <uri>
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: <uri>
- rel: next
method: get
href: <uri>
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.
<br/>
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.<br/>
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.<br/>
**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.<br/>
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.<br/>
**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 <token>'
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.<br/>
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.<br/>
**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
Reference in New Issue View Git Blame Copy Permalink