Patching Considerations

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

A PATCH request is different from a PUT request 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:

When a field is to be removed, you can remove a field by entering a value of

null

When a field is set to

null

, and it does not exist in the current record, it is ignored.

You can remove groups of fields 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.

Example: Updating Expiration Month and Year Values

You can get the existing values by sending a GET request to the payment instrument 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 request to

/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"
      }
    }
  }
}

Example: Removing Card Issue Number (Single Field) and Buyer Information (Container)

First, send a GET request to

/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 request to

/tms/v1/paymentinstrument/<id>

and include the following payload:

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

The result can be seen in the next GET request to

/tms/v1/paymentinstrument/<id>

{
  "_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"
      }
    }
  }
}

Example: Patching an Array

Original value:

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

Patch payload:

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

Final value:

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