Skip to content
developers

Metadata

Guide to using metadata in the Payroc API — attaching custom key-value pairs to resources for auditing, troubleshooting, and third-party system integration.

Browse API reference

Metadata is a feature of our API that you can use to attach additional information to a resource without changing how the resource behaves. You can use metadata to store small pieces of contextual data that aren't part of the standard API fields, for example, who created the resource or how it maps to your internal systems.

Send your metadata as a set of key-value pairs for your own reference, auditing, or troubleshooting. When you retrieve a resource with attached metadata, we echo back the information exactly as you provided it.

What we do with metadata

We don't consume metadata or use it for any internal purposes, but we do:

  • Validate its structure to make sure that it contains key-value pairs.
  • Encrypt it and store it with the resource that you link it to.
  • Return it when you retrieve the resource that it's attached to.

Metadata best practices

Important: Never send sensitive information in metadata, for example, customer information, payment card details, or API keys.

Apply the following best practices when you add metadata to your requests:

  • Use unique key names.
  • Always validate your integration. If you send metadata in the wrong format, we reject the whole request and return a 400 error.
  • Never display metadata in a customer-facing user interface.

How to add metadata to your request

If you send a request that supports metadata, send the metadata object with a series of key-value pairs. You should be aware of the following constraints:

  • You can send up to 20 unique key-value pairs.
  • We accept keys that are String format with a maximum of 50 characters.
  • We accept values that are String format with a maximum of 1024 characters.
  • You can't send nested JSON objects.

Some requests support adding metadata to more than one resource. Our worked examples below cover how to add metadata to one resource in a request, and also how to add metadata to two resources in one request.

Worked example 1 - single resource in a request

I’m integrating against the Create Event Subscription method. It would be useful to indicate the name of the person who is responsible for handling the event if it is fired, as the standard API fields only return the contact’s email address.

To do this, I’m going to add a responsiblePerson key-value pair to the event subscription.

Request

Request

POST https://api.payroc.com/v1/event-subscriptions

Create event subscription with metadata

curl
curl -X POST https://api.payroc.com/v1/event-subscriptions \
     -H "Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "enabled": true,
  "eventTypes": [
    "processingAccount.status.changed"
  ],
  "notifications": [
    {
      "type": "webhook",
      "secret": "aBcD1234eFgH5678iJkL9012mNoP3456",
      "supportEmailAddress": "jane.doe@example.com",
      "uri": "https://my-server/notification/endpoint"
    }
  ],
  "metadata": {
    "responsiblePerson": "Jane Doe"
  }
}'

Create event subscription with metadata

Python
import requests

url = "https://api.payroc.com/v1/event-subscriptions"

payload = {
    "enabled": True,
    "eventTypes": ["processingAccount.status.changed"],
    "notifications": [
        {
            "type": "webhook",
            "secret": "aBcD1234eFgH5678iJkL9012mNoP3456",
            "supportEmailAddress": "jane.doe@example.com",
            "uri": "https://my-server/notification/endpoint"
        }
    ],
    "metadata": { "responsiblePerson": "Jane Doe" }
}
headers = {
    "Idempotency-Key": "8e03978e-40d5-43e8-bc93-6894a57f9324",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())

Create event subscription with metadata

JavaScript
const url = 'https://api.payroc.com/v1/event-subscriptions';
const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '8e03978e-40d5-43e8-bc93-6894a57f9324',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: '{"enabled":true,"eventTypes":["processingAccount.status.changed"],"notifications":[{"type":"webhook","secret":"aBcD1234eFgH5678iJkL9012mNoP3456","supportEmailAddress":"jane.doe@example.com","uri":"https://my-server/notification/endpoint"}],"metadata":{"responsiblePerson":"Jane Doe"}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

Create event subscription with metadata

go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.payroc.com/v1/event-subscriptions"

	payload := strings.NewReader("{\n  \"enabled\": true,\n  \"eventTypes\": [\n    \"processingAccount.status.changed\"\n  ],\n  \"notifications\": [\n    {\n      \"type\": \"webhook\",\n      \"secret\": \"aBcD1234eFgH5678iJkL9012mNoP3456\",\n      \"supportEmailAddress\": \"jane.doe@example.com\",\n      \"uri\": \"https://my-server/notification/endpoint\"\n    }\n  ],\n  \"metadata\": {\n    \"responsiblePerson\": \"Jane Doe\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Idempotency-Key", "8e03978e-40d5-43e8-bc93-6894a57f9324")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}

Create event subscription with metadata

ruby
require 'uri'
require 'net/http'

url = URI("https://api.payroc.com/v1/event-subscriptions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '8e03978e-40d5-43e8-bc93-6894a57f9324'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"enabled\": true,\n  \"eventTypes\": [\n    \"processingAccount.status.changed\"\n  ],\n  \"notifications\": [\n    {\n      \"type\": \"webhook\",\n      \"secret\": \"aBcD1234eFgH5678iJkL9012mNoP3456\",\n      \"supportEmailAddress\": \"jane.doe@example.com\",\n      \"uri\": \"https://my-server/notification/endpoint\"\n    }\n  ],\n  \"metadata\": {\n    \"responsiblePerson\": \"Jane Doe\"\n  }\n}"

response = http.request(request)
puts response.read_body

Create event subscription with metadata

Java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.payroc.com/v1/event-subscriptions")
  .header("Idempotency-Key", "8e03978e-40d5-43e8-bc93-6894a57f9324")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"enabled\": true,\n  \"eventTypes\": [\n    \"processingAccount.status.changed\"\n  ],\n  \"notifications\": [\n    {\n      \"type\": \"webhook\",\n      \"secret\": \"aBcD1234eFgH5678iJkL9012mNoP3456\",\n      \"supportEmailAddress\": \"jane.doe@example.com\",\n      \"uri\": \"https://my-server/notification/endpoint\"\n    }\n  ],\n  \"metadata\": {\n    \"responsiblePerson\": \"Jane Doe\"\n  }\n}")
  .asString();

Create event subscription with metadata

PHP
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.payroc.com/v1/event-subscriptions', [
  'body' => '{
  "enabled": true,
  "eventTypes": [
    "processingAccount.status.changed"
  ],
  "notifications": [
    {
      "type": "webhook",
      "secret": "aBcD1234eFgH5678iJkL9012mNoP3456",
      "supportEmailAddress": "jane.doe@example.com",
      "uri": "https://my-server/notification/endpoint"
    }
  ],
  "metadata": {
    "responsiblePerson": "Jane Doe"
  }
}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
    'Idempotency-Key' => '8e03978e-40d5-43e8-bc93-6894a57f9324',
  ],
]);

echo $response->getBody();

Create event subscription with metadata

C#
using RestSharp;

var client = new RestClient("https://api.payroc.com/v1/event-subscriptions");
var request = new RestRequest(Method.POST);
request.AddHeader("Idempotency-Key", "8e03978e-40d5-43e8-bc93-6894a57f9324");
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"enabled\": true,\n  \"eventTypes\": [\n    \"processingAccount.status.changed\"\n  ],\n  \"notifications\": [\n    {\n      \"type\": \"webhook\",\n      \"secret\": \"aBcD1234eFgH5678iJkL9012mNoP3456\",\n      \"supportEmailAddress\": \"jane.doe@example.com\",\n      \"uri\": \"https://my-server/notification/endpoint\"\n    }\n  ],\n  \"metadata\": {\n    \"responsiblePerson\": \"Jane Doe\"\n  }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

Create event subscription with metadata

swift
import Foundation

let headers = [
  "Idempotency-Key": "8e03978e-40d5-43e8-bc93-6894a57f9324",
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = [
  "enabled": true,
  "eventTypes": ["processingAccount.status.changed"],
  "notifications": [
    [
      "type": "webhook",
      "secret": "aBcD1234eFgH5678iJkL9012mNoP3456",
      "supportEmailAddress": "jane.doe@example.com",
      "uri": "https://my-server/notification/endpoint"
    ]
  ],
  "metadata": ["responsiblePerson": "Jane Doe"]
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.payroc.com/v1/event-subscriptions")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()

Worked example 2 - multiple resources in one request

I'm integrating against the Create Funding Instruction method, which creates a funding instruction and links recipients to it. It would be useful for me to add the following metadata:

  • Name of the person who created the funding instruction for audit purposes.
  • Name of the recipient who is receiving the funds.

To do this, I'm going to add an instructionCreatedBy key-value pair to the funding instruction, and I'm going to add a supplier key-value pair to the recipient object.

Request

Request

POST https://api.payroc.com/v1/funding-instructions

Funding instruction with metadata

curl
curl -X POST https://api.payroc.com/v1/funding-instructions \
     -H "Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "merchants": [
    {
      "merchantId": "4525644354",
      "recipients": [
        {
          "fundingAccountId": 123,
          "paymentMethod": "ACH",
          "amount": {
            "value": 120000,
            "currency": "USD"
          },
          "metadata": {
            "supplier": "IT Support Services"
          }
        }
      ]
    }
  ],
  "metadata": {
    "instructionCreatedBy": "Jane Doe"
  }
}'

Funding instruction with metadata

Python
import requests

url = "https://api.payroc.com/v1/funding-instructions"

payload = {
    "merchants": [
        {
            "merchantId": "4525644354",
            "recipients": [
                {
                    "fundingAccountId": 123,
                    "paymentMethod": "ACH",
                    "amount": {
                        "value": 120000,
                        "currency": "USD"
                    },
                    "metadata": { "supplier": "IT Support Services" }
                }
            ]
        }
    ],
    "metadata": { "instructionCreatedBy": "Jane Doe" }
}
headers = {
    "Idempotency-Key": "8e03978e-40d5-43e8-bc93-6894a57f9324",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())

Funding instruction with metadata

JavaScript
const url = 'https://api.payroc.com/v1/funding-instructions';
const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '8e03978e-40d5-43e8-bc93-6894a57f9324',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: '{"merchants":[{"merchantId":"4525644354","recipients":[{"fundingAccountId":123,"paymentMethod":"ACH","amount":{"value":120000,"currency":"USD"},"metadata":{"supplier":"IT Support Services"}}]}],"metadata":{"instructionCreatedBy":"Jane Doe"}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

Funding instruction with metadata

go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.payroc.com/v1/funding-instructions"

	payload := strings.NewReader("{\n  \"merchants\": [\n    {\n      \"merchantId\": \"4525644354\",\n      \"recipients\": [\n        {\n          \"fundingAccountId\": 123,\n          \"paymentMethod\": \"ACH\",\n          \"amount\": {\n            \"value\": 120000,\n            \"currency\": \"USD\"\n          },\n          \"metadata\": {\n            \"supplier\": \"IT Support Services\"\n          }\n        }\n      ]\n    }\n  ],\n  \"metadata\": {\n    \"instructionCreatedBy\": \"Jane Doe\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Idempotency-Key", "8e03978e-40d5-43e8-bc93-6894a57f9324")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}

Funding instruction with metadata

ruby
require 'uri'
require 'net/http'

url = URI("https://api.payroc.com/v1/funding-instructions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '8e03978e-40d5-43e8-bc93-6894a57f9324'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"merchants\": [\n    {\n      \"merchantId\": \"4525644354\",\n      \"recipients\": [\n        {\n          \"fundingAccountId\": 123,\n          \"paymentMethod\": \"ACH\",\n          \"amount\": {\n            \"value\": 120000,\n            \"currency\": \"USD\"\n          },\n          \"metadata\": {\n            \"supplier\": \"IT Support Services\"\n          }\n        }\n      ]\n    }\n  ],\n  \"metadata\": {\n    \"instructionCreatedBy\": \"Jane Doe\"\n  }\n}"

response = http.request(request)
puts response.read_body

Funding instruction with metadata

Java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.payroc.com/v1/funding-instructions")
  .header("Idempotency-Key", "8e03978e-40d5-43e8-bc93-6894a57f9324")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"merchants\": [\n    {\n      \"merchantId\": \"4525644354\",\n      \"recipients\": [\n        {\n          \"fundingAccountId\": 123,\n          \"paymentMethod\": \"ACH\",\n          \"amount\": {\n            \"value\": 120000,\n            \"currency\": \"USD\"\n          },\n          \"metadata\": {\n            \"supplier\": \"IT Support Services\"\n          }\n        }\n      ]\n    }\n  ],\n  \"metadata\": {\n    \"instructionCreatedBy\": \"Jane Doe\"\n  }\n}")
  .asString();

Funding instruction with metadata

PHP
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.payroc.com/v1/funding-instructions', [
  'body' => '{
  "merchants": [
    {
      "merchantId": "4525644354",
      "recipients": [
        {
          "fundingAccountId": 123,
          "paymentMethod": "ACH",
          "amount": {
            "value": 120000,
            "currency": "USD"
          },
          "metadata": {
            "supplier": "IT Support Services"
          }
        }
      ]
    }
  ],
  "metadata": {
    "instructionCreatedBy": "Jane Doe"
  }
}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
    'Idempotency-Key' => '8e03978e-40d5-43e8-bc93-6894a57f9324',
  ],
]);

echo $response->getBody();

Funding instruction with metadata

C#
using RestSharp;

var client = new RestClient("https://api.payroc.com/v1/funding-instructions");
var request = new RestRequest(Method.POST);
request.AddHeader("Idempotency-Key", "8e03978e-40d5-43e8-bc93-6894a57f9324");
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"merchants\": [\n    {\n      \"merchantId\": \"4525644354\",\n      \"recipients\": [\n        {\n          \"fundingAccountId\": 123,\n          \"paymentMethod\": \"ACH\",\n          \"amount\": {\n            \"value\": 120000,\n            \"currency\": \"USD\"\n          },\n          \"metadata\": {\n            \"supplier\": \"IT Support Services\"\n          }\n        }\n      ]\n    }\n  ],\n  \"metadata\": {\n    \"instructionCreatedBy\": \"Jane Doe\"\n  }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

Funding instruction with metadata

swift
import Foundation

let headers = [
  "Idempotency-Key": "8e03978e-40d5-43e8-bc93-6894a57f9324",
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = [
  "merchants": [
    [
      "merchantId": "4525644354",
      "recipients": [
        [
          "fundingAccountId": 123,
          "paymentMethod": "ACH",
          "amount": [
            "value": 120000,
            "currency": "USD"
          ],
          "metadata": ["supplier": "IT Support Services"]
        ]
      ]
    ]
  ],
  "metadata": ["instructionCreatedBy": "Jane Doe"]
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.payroc.com/v1/funding-instructions")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()

Search documentation

API reference169
Guides118
Knowledge38
legal1
Solutions32
Workflows74
↑↓highlight↵openView all search results

Menu

Theme

Sign out

Your saved plans remain in your organization. This browser’s private draft and account view will be cleared.

Talk to an engineer