Patching within TMS is based on JSON Merge Patch (RFC7396), in which changes follow the same structure being modified as that of a POST, rather than JavaScript Object Notation (JSON) Patch (RFC6902), in which changes are expressed as a set of actions.

A PATCH is different from a PUT in that only the fields that must be changed need to be provided in the request, and those changes are merged with the existing record.

Here are some rules to consider:

If a field is to be removed, it should be supplied with a value of

null

If a field is set to

null

that does not exist in the current record, it will simply be ignored.

Whole collections of fields can be removed by setting the parent container to

null

IMPORTANT

Array values are patched as a whole, so in the patch request, provide the final value that is expected after the patch.

Patching Examples

Below are some use-case examples of patching rules.

Updating Expiration Month and Year Values

You can get the existing values by sending a GET request to the instrument’s ID as shown below:

GET /tms/v1/paymentinstrument/<id>

The response is shown below:

{
  "_links": {
    "self": {
      "href": "https://api.cybersource.com/tms/v1/paymentinstruments/9000000000000000002001"
     }
  },
  "id": "9000000000000000002001",
  "object": "paymentInstrument",
  "state": "ACTIVE",
  "card": {
    "expirationMonth": "09",
    "expirationYear": "2017",
    "type": "visa",
    "issueNumber": "01"
  },
  "_embedded": {
    "instrumentIdentifier": {
      "_links": {
        "self": {
          "href": "https://api.cybersource.com/tms/v1/instrumentidentifiers/9000000000000000001001"
        }
      },
      "id": "9000000000000000001001",
      "object": "instrumentIdentifier",
      "state": "ACTIVE",
      "card": {
        "number": "411111XXXX11112"
      }
    }
  }
}

To update just the card.expirationMonth
and card.expirationYear
fields, send the following PATCH request:

PATCH /tms/v1/paymentinstrument/<id>
{
  "card": {
    "expirationMonth": "10",
    "expirationYear": "2020"
  }
}

You can see the new values by issuing another

GET /tms/v1/paymentinstrument/<id>

. The response is shown below.

{
  "_links": {
    "self": {
      "href": "https://api.cybersource.com/tms/v1/paymentinstruments/9000000000000000002001"
    }
  },
  "id": "9000000000000000002001",
  "object": "paymentInstrument",
  "state": "ACTIVE",
  "card": {
    "expirationMonth": "10",
    "expirationYear": "2020",
    "type": "visa",
    "issueNumber": "01"
  },  "_embedded": {
    "instrumentIdentifier": {
      "_links": {
        "self": {
          "href": "https://api.cybersource.com/tms/v1/instrumentidentifiers/9000000000000000001001"
        }
      },
      "id": "9000000000000000001001",
      "object": "instrumentIdentifier",
      "state": "ACTIVE",
      "card": {
        "number": "411111XXXX11112"
      }
    }
  }
}

Removing Card Issue Number (Single Field) and Buyer Information (container)

First, send a

GET /tms/v1/paymentinstrument/<id>

to see the current values:

{
  "_links": {
    "self": {
      "href": "https://api.cybersource.com/tms/v1/paymentinstruments/9000000000000000002001"
    }
  },
  "id": "9000000000000000002001",
  "object": "paymentInstrument",
  "state": "ACTIVE",
  "card": {
    "expirationMonth": "09",
    "expirationYear": "2017",
    "type": "visa",
    "issueNumber": "01"
  },
  "buyerInformation": {
    "companyTaxID": "12345",
    "currency": "USD"
  },
  "_embedded": {
    "instrumentIdentifier": {
      "_links": {
        "self": {
          "href": "https://api.cybersource.com/tms/v1/instrumentidentifiers/9000000000000000001001"
        }
      },
      "id": "9000000000000000001001",
      "object": "instrumentIdentifier",
      "state": "ACTIVE",
      "card": {
        "number": "411111XXXX11112"
      }
    }
  }
}

Then send a

PATCH /tms/v1/paymentinstrument/<id>

and include the following payload:

{
  "card": {
    "issueNumber": null
  },
"buyerInformation": null
}

The result can be seen in the next

GET /tms/v1/paymentinstrument/<id>

request:

{
  "_links": {
    "self": {
      "href": "https://api.cybersource.com/tms/v1/paymentinstruments/9000000000000000002001"
    }
  },
  "id": "9000000000000000002001",
  "object": "paymentInstrument",
  "state": "ACTIVE",
  "card": {
    "expirationMonth": "09",
    "expirationYear": "2017",
    "type": "visa"
  }
  "_embedded": {
    "instrumentIdentifier": {
      "_links": {
        "self": {
          "href": "https://api.cybersource.com/tms/v1/instrumentidentifiers/9000000000000000001001"
        }
      },
      "id": "9000000000000000001001",
      "object": "instrumentIdentifier",
      "state": "ACTIVE",
      "card": {
        "number": "411111XXXX11112"
      }
    }
  }
}

Patching an Array

Original value:

{
  "a": [
    {
      "b": "c",
      "d": "e"
    }
  ]
}

Patch payload:

{
  "a": [
    {
      "z": "y"
    }
  ]
}

Final value:

{
  "a": [
      {
      "z": "y"
    }
  ]
}