Menu

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, 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"     }   ] }
Back to top