Create pricing intent

Browse API reference

POST/pricing-intentscreatePricingIntent

Use this method to create a pricing intent that you can assign to a processing account.

In the request, you must provide the following:

Processing fees, including the pricing program and the fee to process each transaction.
Gateway fees, including the fee for each transaction handled by our gateway.
Base fees, including maintenance and PCI fees.

In the response, our gateway returns information about the pricing intent and the pricingIntentId, which you need for the following methods:

Create Merchant Platform - Assign the pricing intent to a processing account, when you create the merchant platform and its processing accounts.
Create Processing Account - Assign the pricing intent to a processing account.
Retrieve Pricing Intent - Retrieve information about a pricing intent.
Update Pricing Intent - Update the details of a pricing intent.
Delete Pricing Intent - Delete a pricing intent.
Partially Update Pricing Intent - Partially update the details of a pricing intent.

Parameters

Name	In	Type	Description
`Idempotency-Key`Required	header	`string`	Unique identifier that you generate for each request. You must use the UUID v4 format for the identifier. For more information about the idempotency key, go to Idempotency.

Request body

application/json

Field Edit request inputs →

5.2object
Object that contains information about a pricing intent for Merchant Processing Agreement (MPA) 5.2.
- keystringrequired
  Unique identifier that you can assign to the pricing intent for your own records.
- metadataobject
  Metadata object that contains your custom data.
- baseobjectrequired
  Object that contains information about U.S. base fees.
  - addressVerificationintegernullrequired
    Fee for each address verification request. The value is in the currency's lowest denomination, for example, cents.≥ 0
  - annualFeeobjectrequired
    Object that contains information about the annual fee.+2 more fields at deeper levels — see the full spec
  - batchintegerrequired
    Fee for each batch. The value is in the currency's lowest denomination, for example, cents.≥ 0
  - chargebackinteger
    Fee for each chargeback. The value is in the currency's lowest denomination, for example, cents.750–5000
  - earlyTerminationinteger
    Fee for early termination. The value is in the currency's lowest denomination, for example, cents.19500–59500
  - maintenanceintegerrequired
    Monthly fee for maintenance. The value is in the currency's lowest denomination, for example, cents.≥ 500
  - minimumintegerrequired
    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.≥ 0
  - pciNonComplianceinteger
    Fee that we apply each month if you aren't compliant with PCI standards. The value is in the currency's lowest denomination, for example, cents.3995–10000
  - platinumSecurityobject
    Object that contains information about the Platinum Security fee.+6 more fields at deeper levels — see the full spec
  - regulatoryAssistanceProgramintegernullrequired
    Annual fee for the regulatory assistance program. The value is in the currency's lowest denomination, for example, cents.≥ 0
  - retrievalinteger
    Fee for each retrieval. The value is in the currency's lowest denomination, for example, cents.275–5000
  - voiceAuthorizationinteger
    Fee for each voice authorization. The value is in the currency's lowest denomination, for example, cents.95–200
- countrystringrequired
  Two-digit code for the country that the pricing intent applies to. The format follows the ISO-3166-1 standard.US
- gatewayobject
  Object that contains information about the gateway fees for MPA 5.2.
  - feesobjectrequired
    Object that contains information about the gateway fees.+6 more fields at deeper levels — see the full spec
- processorobject
  Object that contains information about U.S. processor fees.
  - achobject
    Object that contains the fees for ACH transactions.+10 more fields at deeper levels — see the full spec
  - cardobject
    Object that contains information about card fees.+223 more fields at deeper levels — see the full spec
- servicesobject[]
  Object that contains information about our additional services that the merchant can sign up for.
  - option 1object
    Object that contains information about the Hardware Advantage Plan.+2 more fields at deeper levels — see the full spec
  - option 2object
    Object that contains the fees for account updater service.+5 more fields at deeper levels — see the full spec
  - option 3object
    Object that contains the fees for wireless processing.+4 more fields at deeper levels — see the full spec
  - option 4object
    Object that contains the fees for the Clover platform service.+5 more fields at deeper levels — see the full spec
  - option 5object
    Object that contains the fees for the Roc Services gateway.+3 more fields at deeper levels — see the full spec
- versionstringrequired
  Version of the MPA.5.2

Responses

Successful response. We created the pricing intent and it is waiting for approval.

201 Created · application/json

{
  "base": {
    "addressVerification": 5,
    "annualFee": {
      "amount": 100,
      "billInMonth": "june"
    },
    "batch": 1000,
    "chargeback": 2500,
    "earlyTermination": 57500,
    "maintenance": 500,
    "minimum": 100,
    "pciNonCompliance": 4995,
    "platinumSecurity": {
      "amount": 1295,
      "billingFrequency": "monthly"
    },
    "regulatoryAssistanceProgram": 15,
    "retrieval": 1500,
    "voiceAuthorization": 95
  },
  "country": "US",
  "createdDate": "2024-07-02T09:00:00Z",
  "gateway": {
    "fees": {
      "monthly": 2000,
      "perDeviceMonthly": 10,
      "perTransaction": 2000,
      "setup": 5000
    }
  },
  "id": "5",
  "key": "Your-Unique-Identifier",
  "lastUpdatedDate": "2024-07-02T09:00:00Z",
  "metadata": {
    "yourCustomField": "abc123"
  },
  "processor": {
    "ach": {
      "fees": {
        "accountVerification": 100,
        "batch": 1000,
        "discountRateAbove10000": 10,
        "discountRateUnder10000": 5.25,
        "monthlyMinimum": 20000,
        "returns": 400,
        "statement": 800,
        "transaction": 50,
        "unauthorizedReturn": 1999
      }
    },
    "card": {
      "fees": {
        "amex": {
          "transaction": 5,
          "type": "optBlue",
          "volume": 1.25
        },
        "electronicBenefitsTransfer": {
          "transaction": 10
        },
        "mastercardVisaDiscover": {
          "transaction": 5,
          "volume": 1.25
        },
        "pinDebit": {
          "additionalDiscount": 1.25,
          "monthlyAccess": 1200,
          "transaction": 10
        },
        "specialityCards": {
          "transaction": 10
        }
      },
      "planType": "interchangePlus"
    }
  },
  "services": [
    {
      "enabled": true,
      "name": "hardwareAdvantagePlan"
    }
  ],
  "status": "pendingReview",
  "version": "5.2"
}

Response schema · 33 of 301 fields

5.2object
Object that contains information about a pricing intent for Merchant Processing Agreement (MPA) 5.2.
- createdDatestringdate-time
  Date and time that we received your request to create the pricing intent. We return this value in the ISO-8601 format.
- idstring
  Unique identifier of the pricing intent.
- keystringrequired
  Unique identifier that you can assign to the pricing intent for your own records.
- lastUpdatedDatestringdate-time
  Date and time that the pricing intent was last modified. We return this value in the ISO-8601 format.
- metadataobject
  Metadata object that contains your custom data.
- statusstring
  Status of the pricing intent. The value can be one of the following: active We have approved the pricing intent. pendingReview We have not yet reviewed the pricing intent. rejected We have rejected the pricing intent.activependingReviewrejected
- baseobjectrequired
  Object that contains information about U.S. base fees.
  - addressVerificationintegernullrequired
    Fee for each address verification request. The value is in the currency's lowest denomination, for example, cents.≥ 0
  - annualFeeobjectrequired
    Object that contains information about the annual fee.+2 more fields at deeper levels — see the full spec
  - batchintegerrequired
    Fee for each batch. The value is in the currency's lowest denomination, for example, cents.≥ 0
  - chargebackinteger
    Fee for each chargeback. The value is in the currency's lowest denomination, for example, cents.750–5000
  - earlyTerminationinteger
    Fee for early termination. The value is in the currency's lowest denomination, for example, cents.19500–59500
  - maintenanceintegerrequired
    Monthly fee for maintenance. The value is in the currency's lowest denomination, for example, cents.≥ 500
  - minimumintegerrequired
    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.≥ 0
  - pciNonComplianceinteger
    Fee that we apply each month if you aren't compliant with PCI standards. The value is in the currency's lowest denomination, for example, cents.3995–10000
  - platinumSecurityobject
    Object that contains information about the Platinum Security fee.+6 more fields at deeper levels — see the full spec
  - regulatoryAssistanceProgramintegernullrequired
    Annual fee for the regulatory assistance program. The value is in the currency's lowest denomination, for example, cents.≥ 0
  - retrievalinteger
    Fee for each retrieval. The value is in the currency's lowest denomination, for example, cents.275–5000
  - voiceAuthorizationinteger
    Fee for each voice authorization. The value is in the currency's lowest denomination, for example, cents.95–200
- countrystringrequired
  Two-digit code for the country that the pricing intent applies to. The format follows the ISO-3166-1 standard.US
- gatewayobject
  Object that contains information about the gateway fees for MPA 5.2.
  - feesobjectrequired
    Object that contains information about the gateway fees.+6 more fields at deeper levels — see the full spec
- processorobject
  Object that contains information about U.S. processor fees.
  - achobject
    Object that contains the fees for ACH transactions.+10 more fields at deeper levels — see the full spec
  - cardobject
    Object that contains information about card fees.+225 more fields at deeper levels — see the full spec
- servicesobject[]
  Object that contains information about our additional services that the merchant can sign up for.
  - option 1object
    Object that contains information about the Hardware Advantage Plan.+2 more fields at deeper levels — see the full spec
  - option 2object
    Object that contains the fees for account updater service.+5 more fields at deeper levels — see the full spec
  - option 3object
    Object that contains the fees for wireless processing.+4 more fields at deeper levels — see the full spec
  - option 4object
    Object that contains the fees for the Clover platform service.+5 more fields at deeper levels — see the full spec
  - option 5object
    Object that contains the fees for the Roc Services gateway.+3 more fields at deeper levels — see the full spec
- versionstringrequired
  Version of the MPA.5.2

Validation error

400 Bad Request · application/problem+json

{
  "detail": "An 'Idempotency-Key' must be supplied for this request",
  "status": 400,
  "title": "Idempotency-Key header missing",
  "type": "https://docs.payroc.com/api/errors#idempotency-key-missing"
}

Response schema · 8 fields

detailstringrequired
Explanation of the problem
errorsobject[]
- detailstring
  Short detail of the validation errors
- messagestring
  Error message
- parameterstring
  The parameter or field causing the issues
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type

Identity could not be verified

401 Unauthorized · application/problem+json

{
  "detail": "Your identity could not be verified",
  "status": 401,
  "title": "Not Authorized",
  "type": "https://docs.payroc.com/api/errors#not-authorized"
}

Response schema · 4 fields

detailstringrequired
Explanation of the problem
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type

Do not have permissions to perform this action

403 Forbidden · application/problem+json

{
  "detail": "You do not have the required permissions to perform this action",
  "instance": "https://api.payroc.com/v1/exampleResource/3",
  "resource": "exampleResource",
  "status": 403,
  "title": "Forbidden",
  "type": "https://docs.payroc.com/api/errors#forbidden"
}

Response schema · 6 fields

detailstringrequired
Explanation of the problem
instancestring
Resource path the action was attempted on
resourcestring
Resource the action was attempted on
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type

Not acceptable

406 Not Acceptable · application/problem+json

{
  "detail": "Resource does not support the representation requested",
  "status": 406,
  "title": "Not acceptable",
  "type": "https://docs.payroc.com/api/errors#not-acceptable"
}

Response schema · 4 fields

detailstringrequired
Explanation of the problem
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type

Conflict

409 Conflict · application/problem+json

{
  "detail": "'Idempotency-Key' is already in use against a different request",
  "status": 409,
  "title": "Idempotency-Key in use",
  "type": "https://docs.payroc.com/api/errors#idempotency-key-in-use"
}

Response schema · 13 fields

detailstringrequired
Explanation of the problem
errorsobject[]
- detailstring
  Short detail of the validation errors
- messagestring
  Error message
- parameterstring
  The parameter or field causing the issues
instancestring
Resource path to the existing resource
linkobject
Object that contains HATEOAS links for the resource.
- hrefstringrequired
  URL of the target resource.
- methodstringrequired
  HTTP method that you need to use with the target resource.
- relstringrequired
  Indicates the relationship between the current resource and the target resource.
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type

An error has occured

500 Internal Server Error · application/problem+json

{
  "detail": "We are unable to process your request at this time",
  "errors": [
    {
      "message": "Service offline"
    }
  ],
  "status": 500,
  "title": "Api error",
  "type": "https://docs.payroc.com/api/errors#api-error"
}

Response schema · 6 fields

detailstringrequired
Explanation of the problem
errorsobject[]
- messagestring
  Error message
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type

Used in workflows

create-pricing-intent manage-pricing-intents