voidPayment

Requires at least one of the permissions payments:payment:void or purchase:payment:void.

Voids a payment. A payment that is DRAFT or PENDING with nothing allocated is simply cancelled and the partner balance it took is restored. A settled payment has its live allocations reversed and the posted balance restored. A payment taken through an online gateway also raises one credit note for the full amount, with no refund call to the provider. Money already given back by cancelling an invoice is not given back twice. A payment already voided, reversed or refunded is returned unchanged.

Errors: a failed call returns a GraphQL errors entry, not a field on the result, and data may be null or partial. Read the entry's extensions.code and message; every shape and code is in the Error reference.

Example:

GraphQL

mutation VoidPayment($input: VoidPaymentInput!) {
  voidPayment(input: $input) {
    id
    checkNumber
    currencyCode
    paymentNumber
    referenceNumber
    status
    allocations {
      id
      invoiceNumber
      paymentNumber
      createdAt
      amount
      appliedFromAdvance
    }
  }
}

cURL

curl -X POST "https://<api-host>/graphql" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  --data @- <<'EOF'
{
  "query": "mutation VoidPayment($input: VoidPaymentInput!) {\n  voidPayment(input: $input) {\n    id\n    checkNumber\n    currencyCode\n    paymentNumber\n    referenceNumber\n    status\n    allocations {\n      id\n      invoiceNumber\n      paymentNumber\n      createdAt\n      amount\n      appliedFromAdvance\n    }\n  }\n}",
  "variables": {
    "input": {
      "paymentId": "id"
    }
  }
}
EOF

Variables:

{
  "input": {
    "paymentId": "id"
  }
}

Response:

{
  "data": {
    "voidPayment": {
      "id": "id",
      "checkNumber": "string",
      "currencyCode": "string",
      "paymentNumber": "string",
      "referenceNumber": "string",
      "status": "APPROVED",
      "allocations": [
        {
          "id": "id",
          "invoiceNumber": "string",
          "paymentNumber": "string",
          "createdAt": "2025-01-15T00:00:00Z",
          "amount": 0,
          "appliedFromAdvance": true
        }
      ]
    }
  }
}

Void a payment with a reason:

GraphQL

mutation VoidPayment($input: VoidPaymentInput!) {
  voidPayment(input: $input) {
    id
    paymentNumber
    status
  }
}

cURL

curl -X POST "https://<api-host>/graphql" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  --data @- <<'EOF'
{
  "query": "mutation VoidPayment($input: VoidPaymentInput!) {\n  voidPayment(input: $input) {\n    id\n    paymentNumber\n    status\n  }\n}",
  "variables": {
    "input": {
      "paymentId": "PAYMENT_ID",
      "reason": "Entered in error"
    }
  }
}
EOF

Variables:

{
  "input": {
    "paymentId": "PAYMENT_ID",
    "reason": "Entered in error"
  }
}

Response:

{
  "data": {
    "voidPayment": {
      "id": "PAYMENT_ID",
      "paymentNumber": "PAYMENT_NUMBER",
      "status": "CANCELLED"
    }
  }
}

voidPayment(
  input: VoidPaymentInput!
): Payment!

Arguments

voidPayment.input ● VoidPaymentInput! non-null input

The payment to void and the reason.

Type

Payment object

A payment made out to a vendor or a collection received from a customer, with its allocations to invoices.