Manage workflows

Last updated: 14th July 2022

Learn how to manage your workflows using our API.

Find out how to:

Return all workflows
Return a single workflow
Add a new workflow
Update the name of a workflow
Update the actions of a workflow
Update the conditions of a workflow
Delete a workflow
Test a workflow

Return all workflows

Use this API request to view all your previously configured workflows.

Endpoints

For the full API specification, see the API reference.

get

https://api.checkout.com/workflows

Response example

{
  "data": [
    {
      "id": "wf_wlu3wxc26jounofs5iez75qaqa",
      "name": "Webhooks workflow",
      "active": true,
      "_links": {
        "self": {
          "href": "https://api.checkout.com/workflows/wf_wlu3wxc26jounofs5iez75qaqa"
        }
      }
    }
  ]
}

Other possible responses:

401 - Unauthorized
500 - Internal error

Return a single workflow

Use this API request to view the details of a single workflow using its workflow ID.

Use the details below to set up your request.

Endpoints

For the full API specification, see the API reference.

get

https://api.checkout.com/workflows/{workflowId}

Response example

Below is an example successful response where the details of the configured workflow are visible.

{
    "id": "<WORKFLOW_ID>",
    "name": "Single workflow example",
    "active": true,
    "conditions": [
        {
            "id": "<WORKFLOW_CONDITION_ID>",
            "type": "event",
            "events": {
                "gwc_notifier1": [
                    "payment_approved"
                ]
            }
        },
        {
            "id": "<WORKFLOW_CONDITION_ID>",
            "type": "entity",
            "entities": [
                "<ENTITY_ID>>"
            ]
        },
        {
            "id": "<WORKFLOW_CONDITION_ID>",
            "type": "processing_channel",
            "processing_channels": [
                "<PROCESSING_CHANNEL_ID>"
            ]
        }
    ],
    "actions": [
        {
            "id": "<WORKFLOW_ACTION_ID>",
            "type": "webhook",
            "url": "https://devapi.ckotech.co/webhooktester/webhooks/testPC_good_test2",
            "headers": {
                "Authorization": "secr******"
            },
            "signature": {
                "method": "HMACSHA256",
                "key": "signa********"
            }
        }
    ],
    "_links": {
        "self": {
            "href": "https://flow.cko-qa.ckotech.co/workflows/<WORKFLOW_ID>"
        }
    }
}

Other possible responses:

401 - Unauthorized
404 - Workflow not Found
500 - Internal error

Add a new workflow

Use this API request to add a new workflow.

Endpoints

For the full API specification, see the API reference.

post

https://api.checkout.com/workflows

Request example

{
  "name": "Webhooks workflow",
  "active": true,
  "conditions": [
    {
      "type": "event",
      "events": {
        "gateway": [
          "payment_approved",
          "payment_declined",
          "card_verification_declined",
          "card_verified",
          "payment_authorization_incremented",
          "payment_authorization_increment_declined",
          "payment_capture_declined",
          "payment_captured",
          "payment_refund_declined",
          "payment_refunded",
          "payment_void_declined",
          "payment_voided"
        ],
        "dispute": [
          "dispute_canceled",
          "dispute_evidence_required",
          "dispute_expired",
          "dispute_lost",
          "dispute_resolved",
          "dispute_won"
        ]
      }
    },
    {
      "type": "entity",
      "entities": [
        "ent_xyfdshfudosfdshfdiosfds",
        "ent_fidjosfjdisofdjsifdosfu"
      ]
    },
    {
      "type": "processing_channel",
      "processing_channels": [
        "pc_axclravnqf5u5ejkweijnp5zc4"
      ]
    }
  ],
  "actions": [
    {
      "type": "webhook",
      "url": "https://example.com/webhooks",
      "headers": {
        "Authorization": "70ed20ff-ba31-4ea3-b3ef-772f2be1cbdf"
      },
      "signature": {
        "method": "HMACSHA256",
        "key": "8V8x0dLK%AyD*DNS8JJr"
      }
    }
  ]
}

Response example

Below is an example successful response with the details of the additional workflow.

{
  "id": "wf_wlu3wxc26jounofs5iez75qaqa",
  "_links": {
    "self": {
      "href": "https://api.checkout.com/workflows/wf_wlu3wxc26jounofs5iez75qaqa"
    }
  }
}

Other possible responses:

401 - Unauthorized
404 - Invalid data was sent
500 - Internal error

Update the name of a workflow

Use the following endpoint to update the name of a previously created workflow, passing the existing workflow's ID in the path and the new name for the workflow in the request body.

You can find the full specification in our API reference.

Endpoints

For the full API specification, see the API reference.

patch

https://api.checkout.com/workflows/{workflowId}

Request example

{
  "name": "Webhooks workflow",
  "active": true
}

Response example

Below is an example successful response with the details of the additional workflow.

{
  "name": "Webhooks workflow",
  "active": true
}

401 - Unauthorized
404 - Workflow not found
500 - Internal error

Update the actions of a workflow

To update the actions of a workflow, use the following endpoint, passing the workflow's ID and action ID in the path, and the details you want to update in the request body.

You can find the full specification in our API reference.

Endpoints

For the full API specification, see the API reference.

put

https://api.checkout.com/workflows/{workflowId}/actions/{workflowActionId}

Request example

{
  "type": "webhook",
  "url": "https://example.com/webhooks/checkout",
  "headers": {
    "Authorization": "70ed20ff-ba31-4ea3-b3ef-772f2be1cbdf"
  },
  "signature": {
    "method": "HMACSHA256",
    "key": "public-signing-key"
  }
}

Response

If you receive a 200 success response, the workflow action was successfully updated.

Other possible responses:

401 - Unauthorized
404 - Workflow or workflow action not found
422 - Invalid data was sent
500 - Internal error

Update the conditions of a workflow

To update the conditions of a workflow, use the following endpoint, passing the workflow's ID and condition ID in the path, and the details you want to update in the request body.

You can find the full specification in our API reference.

Endpoints

For the full API specification, see the API reference.

put

https://api.checkout.com/workflows/{workflowId}/conditions/{workflowConditionId}

Request example

{
  "type": "event",
  "events": {
    "gateway": [
      "card_verified",
      "card_verification_declined",
      "payment_approved",
      "payment_pending",
      "payment_declined",
      "payment_voided",
      "payment_captured",
      "payment_refunded"
    ],
    "dispute": [
      "dispute_canceled",
      "dispute_evidence_required",
      "dispute_expired",
      "dispute_lost",
      "dispute_resolved",
      "dispute_won"
    ]
  }
}

Response

If you receive a 200 success response, the workflow condition was successfully updated.

Other possible responses:

401 - Unauthorized
404 - Workflow or workflow condition not found
422 - Invalid data was sent
500 - Internal error

Delete a workflow

Use this API request to delete an existing workflow. The actions of already executed workflows will be still processed.

Endpoints

For the full API specification, see the API reference.

delete

https://api.checkout.com/workflows/{workflowId}

Response

A 204 response signals that the workflow was successfully deleted.

Other possible responses:

401 - Unauthorized
404 - Workflow not found
500 - Internal error

Test a workflow

Before setting up a workflow in production, you can test the workflow configuration in sandbox. If the test workflow is valid, the actions for all included event types will be triggered.

Endpoint

For the full API specification, see the API reference.

post

https://api.sandbox.checkout.com/workflows/{workflowId}/test

Request example

{
"event_types": [
  "payment_approved",
  "payment_declined",
  "card_verification_declined",
  "card_verified",
  "payment_captured",
  "payment_refunded",
  "payment_voided",
  "dispute_canceled",
  "dispute_evidence_required",
  "dispute_expired",
  "dispute_lost",
  "dispute_resolved",
  "dispute_won"
  ]
}

Response

A 204 response signals that the test workflow was successfully triggered.

Other possible responses:

401 - Unauthorized
404 - Workflow not found
422 - Invalid data was sent
500 - Internal error

Return all workflows

Endpoints

Response example

Return a single workflow

Endpoints

Response example

Add a new workflow

Endpoints

Request example

Response example

Update the name of a workflow

Endpoints

Request example

Response example

Update the actions of a workflow

Endpoints

Request example

Response

Update the conditions of a workflow

Endpoints

Request example

Response

Delete a workflow

Endpoints

Response

Test a workflow

Endpoint

Request example

Response

On this page