How-to: Integrate with JSON Schema

To facilitate the effective passing of travel rule and beneficiary data, CPN provides JSON Schema that gives a clear, machine-readable contract you can validate your response against. This guide provides information about how to integrate with the JSON Schema returned by the requirements endpoint.

Use the following steps to retrieve JSON Schema for a given quote and respond with the required information.

Call the payment requirements endpoint. The API returns two JSON Schema objects, one for the travelRule and one for the beneficiaryAccount.

Using the schemas as a blueprint, construct your travelRule and beneficiaryAccount data as JSON objects. For example, if the travelRule scheme requires the BENEFICIARY_ADDRESS field, you should create a nested JSON object for the address fields, as defined by the schema's properties and $defs.

Before encrypting the response for transit, CPN expects that you perform client-side validation on the data. Using a JSON Schema validation library, check your constructed JSON objects against the schemas from Step 1. This should catch any structural or formatting errors before you interact with the CPN API.

Once validated, convert your JSON objects to strings and encrypt them. Follow How-to: Encrypt Travel Rule and Beneficiary Account Data to encrypt them for transit.

Send the encrypted payload to the create a payment endpoint. Each of the travelRule and beneficiaryAccount fields should be an object containing the version of the schema and the encrypted data.

The following is an example payload:

{
  "quoteId": "d2571d8d-0090-4bea-bee4-2b619ded4622",
  "idempotencyKey": "cb8b2a7a-fce7-4493-81dd-c6aa003f90ee",
  "customerRefId": "CID-98374561",
  "useCase": "B2B",
  "reasonForPayment": "PMT001",
  "senderAddress": "0x0ebb840b744588fdbb9f61e54ab4fd0677997b2a",
  "blockchain": "MATIC-AMOY",
  "travelRule": {
    "version": 1,
    "data": "ENCRYPTED_V2_TRAVEL_RULE_JSON_OBJECT"
  },
  "beneficiaryAccount": {
    "version": 1,
    "data": "ENCRYPTED_V2_BENEFICIARY_ACCOUNT_JSON_OBJECT"
  }
}