Menu
- Manage Webhook Subscriptions
- Customer Tokens
- Manage Customer Tokens
- Shipping Address Tokens
- Customer Payment Instrument Tokens
- Manage Customer Payment Instrument Tokens
- Payment Instrument Tokens
- Manage Payment Instrument Tokens
- Instrument Identifier Tokens
- Manage Instrument Identifier Tokens
- Network Tokens for Partners
- Manage Webhook Subscriptions
- Customer Tokens
- Manage Customer Tokens
- Shipping Address Tokens
- Customer Payment Instrument Tokens
- Manage Customer Payment Instrument Tokens
- Payment Instrument Tokens
- Manage Payment Instrument Tokens
- Instrument Identifier Tokens
- Manage Instrument Identifier Tokens
- Network Tokens for Partners
On This Page
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 ofnull.
- When a field is set tonull, and it does not exist in the current record, it is ignored.
- You can remove groups of fields by setting the parent container tonull.
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" } ] }