Partially update pricing intent

Browse API reference

PATCH/pricing-intents/{pricingIntentId}patchPricingIntent

Use this method to partially update a pricing intent. Structure your request to follow the RFC 6902 standard.

If you update a pricing intent, it won't affect merchants you've previously onboarded.

To update a pricing intent, you need its pricingIntentId. Our gateway returned the pricingIntentId in the response of the Create Pricing Intent method.

Note: If you don't have the pricingIntentId, use our List Pricing Intents method to search for the pricing intent.

You can update the following details about a pricing intent:

Fees, including the base fees, processor fees, and gateway fees.
Custom name for the pricing intent.
Additional services that merchants can sign up for.

Parameters

Name	In	Type	Description
`pricingIntentId`Required	path	`string`	Unique identifier that we assigned to the pricing intent.
`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 →

Patch Add Operationobject
A Patch Add Operation.
- opstringrequired
  add operation.add
- pathstringrequired
  Location where you want to add the value. The format for this value is JSON Pointer.
- valueobjectrequired
  Value that you want to add to the resource.
Patch Remove Operationobject
A Patch Remove Operation.
- opstringrequired
  remove operation.remove
- pathstringrequired
  Location of the value that you want to remove. The format for this value is JSON Pointer.
Patch Replace Operationobject
A Patch Replace Operation.
- opstringrequired
  replace operation.replace
- pathstringrequired
  Location of the value that you want to replace. The format for this value is JSON Pointer.
- valueobjectrequired
  Value that you want to use as the replacement.
Patch Move Operationobject
A Patch Move Operation.
- fromstringrequired
  Location of the value that you want to move. The format for this value is JSON Pointer.
- opstringrequired
  move operation.move
- pathstringrequired
  Location where you want to move the value to. The format for this value is JSON Pointer.
Patch Copy Operationobject
A Patch Copy Operation.
- fromstringrequired
  Location of the value that you want to copy. The format for this value is JSON Pointer.
- opstringrequired
  copy operation.copy
- pathstringrequired
  Location where you want to copy the value to. The format for this value is JSON Pointer.
Patch Test Operationobject
A Patch Test Operation.
- opstringrequired
  test operation.test
- pathstringrequired
  Location of the value that you want to test. The format for this value is JSON Pointer.
- valueobjectrequired
  Value that you want to compare with the current value at the path.

Responses

Successful request. We updated the pricing intent.

200 OK · 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": 1000,
      "perDeviceMonthly": 0,
      "perTransaction": 0,
      "setup": 25000
    }
  },
  "id": "5",
  "key": "string",
  "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": 10,
          "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

Resource not found

404 Not Found · application/problem+json

{
  "detail": "Resource not found",
  "resource": "(The Type of the Resource)",
  "status": 404,
  "title": "Not found",
  "type": "https://docs.payroc.com/api/errors#not-found"
}

Response schema · 5 fields

detailstringrequired
Explanation of the problem
resourcestring
Resource that was not found
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

patch-a-pricing-intent