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

Pagination

Responses can indicate pagination if you include the 
limit
 and 
offset
 fields in your request.
Parameter
Description
limit
Controls the maximum number of items that can be returned for a single request. The default is 20; the maximum is 100.
If you set a limit greater than 100, the following error results:
Http Status: 400 Bad Request
Body
{
  "errors": [
    {
      "type": "invalidParameters",
      "message": "Invalid parameter values",
      "details": [
        {
          "name": "limit"
        }
      ]
    }
  ]
}
offset
Controls the starting point within the collection of results. Defaults to 
0
.
Setting a zero offset retrieves the first item in the collection.
For example, if you have a collection of 15 items to be retrieved from a resource, and you specify 
limit=5
 , you can retrieve the entire set of results in three successive requests by varying the offset value: 
offset=0
, 
offset=5
, and 
offset=10
.
An offset greater than the number of results does not return an embedded object.

Pagination Response Header

Header
Description
X-total-count
Returns total records count regardless of pagination.

Pagination Response Body Fields

Field
Description
"object":"collection"
Shows that the response is a collection of objects.
"offset": 40
The offset parameter used in the request.
"limit": 20
The limit parameter used in the request.
"count": 20
The number of objects returned.
"total": 87
The total number of objects.

Examples

Pagination Example 1
This example shows a request for objects 41 to 60.
Request
GET 
https://api.cybersource.com
/tms/v1/instrumentidentifiers/5BAAD18F8091052CE0539399D30AAB2F/paymentinstruments?offset=40&limit=20
For merchants in India, the Production endpoint is 
https://api.in.cybersource.com/
IMPORTANT
  • If you are on the first collection, the previous link would not be included.
  • If you are on the last collection, the next link would not be included.
  • All other links are always included. For example, if there was only one collection of results, the URL for 
    self
    , 
    first
    , and 
    last
     links would be the same.
Response
{
  "_links": {
    "self": {
      "href": "
https://api.cybersource.com
/tms/v1/instrumentidentifiers/5BAAD18F8091052CE0539399D30AAB2F/paymentinstruments?offset=40&limit=20"
    },
    "first": {
      "href": "
https://api.cybersource.com
/tms/v1/instrumentidentifiers/5BAAD18F8091052CE0539399D30AAB2F/paymentinstruments?offset=0&limit=20"
    },
    "prev": {
      "href": "
https://api.cybersource.com
/tms/v1/instrumentidentifiers/5BAAD18F8091052CE0539399D30AAB2F/paymentinstruments?offset=20&limit=20"
    },
    "next": {
      "href": "
https://api.cybersource.com
/tms/v1/instrumentidentifiers/5BAAD18F8091052CE0539399D30AAB2F/paymentinstruments?offset=60&limit=20"
    },
    "last": {
      "href": "
https://api.cybersource.com
/tms/v1/instrumentidentifiers/5BAAD18F8091052CE0539399D30AAB2F/paymentinstruments?offset=80&limit=20"
    }
  },
  "object":"collection",
  "offset": 40,
  "limit": 20,
  "count": 20,
  "total": 87,
  "_embedded": {
    <array data>
  }
}
Pagination Example 2 - Offset to Limit Relationship
This example shows a request for objects 3 to 6, from a total of 8 objects.
The example below shows the second collection of results and highlights that the previous page link will not change the user’s original limit parameter value.
This means that the previous collection will contain objects 0-3, and therefore collection 1 and collection 2 will both contain object 3.
Request
GET 
https://api.cybersource.com
/tms/v1/instrumentidentifiers/5BAAD18F8091052CE0539399D30AAB2F/paymentinstruments?offset=3&limit=4

Figure:

Offset to Limit Relationship
Response
{
  "_links": {
    "self": {
      "href": "
https://api.cybersource.com
/tms/v1/instrumentidentifiers/5BAAD18F8091052CE0539399D30AAB2F/paymentinstruments?offset=3&limit=4"
    },
    "first": {
      "href": "
https://api.cybersource.com
/tms/v1/instrumentidentifiers/5BAAD18F8091052CE0539399D30AAB2F/paymentinstruments?offset=0&limit=4"
    },
    "prev": {
      "href": "
https://api.cybersource.com
/tms/v1/instrumentidentifiers/5BAAD18F8091052CE0539399D30AAB2F/paymentinstruments?offset=0&limit=4"
    },
    "next": {
      "href": "
https://api.cybersource.com
/tms/v1/instrumentidentifiers/5BAAD18F8091052CE0539399D30AAB2F/paymentinstruments?offset=7&limit=4"
    },
    "last": {
      "href": "
https://api.cybersource.com
/tms/v1/instrumentidentifiers/5BAAD18F8091052CE0539399D30AAB2F/paymentinstruments?offset=7&limit=4"
    }
  },
  "object":"collection",
  "offset": 3,
  "limit": 4,
  "count": 4,
  "total": 8,
  "_embedded": {
    <array data>
  }
}
Patching Considerations