Partially update event subscription

Browse API reference

PATCH/event-subscriptions/{subscriptionId}patchEventSubscription

Use this method to partially update an event subscription. Structure your request to follow the RFC 6902 standard.

To update an event subscription, you need its subscriptionId. Our gateway returned the subscriptionId in the id field in the response of the Create Event Subscription method.

Note: If you don't have the subscriptionId, use our List Event Subscriptions method to search for the subscription.

You can update the following properties of an event subscription:

eventTypes - Subscribe to new events or remove events that you are subscribed to.
notifications - Information about your endpoint and who we email if we can't contact your endpoint.
enabled - Turn on or turn off notifications for the subscription.

Parameters

Name	In	Type	Description
`subscriptionId`Required	path	`integer`	Unique identifier that we assigned to the event subscription. Note: Our gateway returned the subscriptionId in the id field in the response of the Create Event Subscription method.
`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 event subscription.

200 OK · application/json

{
  "enabled": true,
  "eventTypes": [
    "processingAccount.status.changed",
    "terminalOrder.status.changed"
  ],
  "id": 2565435189324,
  "metadata": {
    "yourCustomField": "abc123"
  },
  "notifications": [
    {
      "secret": "**********oP3456",
      "supportEmailAddress": "jane.doe@example.com",
      "type": "webhook",
      "uri": "https://my-server/notification/endpoint"
    }
  ],
  "status": "registered"
}

Response schema · 11 fields

enabledbooleanrequired
Indicates if we should notify you when the event occurs. The value is one of the following: true We notify you when the event occurs. false We don't notify you when the event occurs.
eventTypesstring[]required
Array of events that you want to subscribe to. For a list of events, go to Events List.
idintegerint64
Unique identifier that we assigned to the event subscription.
metadataobject
Object that you can send to include custom data in the request. For more information about how to use metadata, go to Metadata.
notificationsobject[]required
Array of polymorphic notification objects that contain information about how we contact you when an event occurs.
- option 1object
  - secretstringrequired
    String that we send with a notification so that you can ensure it is a valid notification from our gateway. We include the value in the Payroc-Secret header parameter in the webhook call. Note: In the response, we truncate the secret to the last 16 characters and mask the first 10 characters.16–64 chars
  - supportEmailAddressstringrequired
    Email address of the person or team that we contact if we can't deliver notifications.
  - typestringrequired
    Type of notification method. Note: To receive notifications by webhook, your server must be able to handle POST requests.webhook
  - uristringrequired
    Public endpoint that we send notifications to.
statusstring
Status of the subscription. We return one of the following values: registered You have set up the subscription, and we will notify you when an event occurs. suspended We have deactivated the event subscription, and we won't notify you when an event occurs. failed We couldn't contact your URI endpoint. We email the supportEmailAddress.registeredsuspendedfailed

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

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-an-event-subscription